Skip to content

Rest API - UX/UI best practices

ow For clients who are using the TopPlace™ Rest API, the team here at TopPlace has compiled a list of recommendations based on learnings from previous integrations as well as what we have seen work with clients.

General notes

Always maintain your own internal design standards

One of the most common issues we encounter after a "gone wrong" integration is the phrase "we broke our own design rules". Breaking your own design rules disrupts the normal user flow and normally has a negative effect on users and KPIs.

Advice: Maintain your own internal design standards. If you are encountering issues, then please contact the AVUXI team for help.

Ideas for layouts

Advice: The best way to understand what has worked for other clients is to look at the various TopPlace™ Plug & Play templates available. They will help inspire your design/ UX/ UI team and help them understand what is important and what works with users.

Multiple iterations may be required. 

Unfortunately, not everything can always go super smoothly 1st time around. The 1st iteration can sometimes be a totally new way (and non-validated) way to display the TopPlace™ data. It will most likely not produce great results.

Advice: If KPIs are not moving, obtain qualitative user feedback and see how the information is being perceived.

Be careful of information overload

Not having enough info is bad, but too much info is bad too. It is very important to achieve that careful balance between easy visual cognition and information displayed, that works in a positive way. The products we offer as plug&play may not be ideal for your specific layout but have been tested to work. We have discarded many layout options that did not work too well.

Advice: Make sure the information displayed is relevant and useful to your users.

Combining multiple features will yield better results

Advice: Highlighting the best location options (via heat maps, scores, badges, texts etc) is meant to help potential bookers identify faster and feel more certain when making a booking choice/decision (from the multiple options presented).

Travel Agents (Professionals) vs End Users

Travel Agents will visit the content multiple times a day in different locations.

Advice: The Heat Map map layer has been found to be highly valued by professionals who do regular searches.

Advice 2: Ensure you provide interesting and relevant training material.


Location Scores: Specific notes:

Users must understand quickly

Users must understand what they see at first sight, intuitively, for a new element to produce a positive result. Any cognitive friction may render the location context information useless.

Advice: Place the scores in a location that is appropriate and make sure they are clearly labelled.

Show scores out of 10, not 100.

The Location Scores in the Rest API are provided as whole numbers, from 1 to 99. This is a format that is designed to be easier for developers.

Advice: We recommended showing these as numbers out of 10 rather than 100. i.e. divide everything by 10.

Numbers and associated Wording

Adding words to describe the rating helps re-enforce the users understanding.

Advice: We recommend you use the following wording associated with the following scores:

  • Scores of 9.5+ = Superb
  • Scores of 7.5 to 9.4 = Very Good
  • Scores of 5.5 to 7.4 = Good
  • Scores of 5.4 and below: Do not display.

AVUXI research has shown that displaying scores below 5.4 has a negative impact on users, often in resulting in a negative impact on KPIs.

These numbers are final display numbers. The rest API will return the number as an integer from 1 to 99. Divide this number by 10 to get the scores above.


Heat Map & Map Layers: specific notes

Explanation of heatmap

The heat map can be a valuable tool for users, but without an explanation, users can find it annoying or distracting.

Advice: Ensure there is sufficient explanation accompanying the heat map to allow users to understand it. Use the Heat Map Plug & Play templates as a source of information useful to users.


Points of Interest: specific notes

A simple list may not be enough

Simply displaying a list of nearby Points of Interest often does not lead to a significant change in KPIs.

Advice: Consider placing the list next to a map along with some other local area information. e.g. Location Scores.

Ensure the list is not too long

There are up to 80 POIs available in a single API call. Displaying every single POI often confuses users who don't know where to look.

Advice: Lists are good, but keep them short & relevant. If you want to show more than 15-20 POIs, break them down into sub-lists and title them accordingly. e.g. Sightseeing POIs vs Eating & Nightlife POIs.


Other recommended pages

KPI changes as a result of TopPlace (support page coming soon)

TopPlace™ Attribution requirements

↑