TopPlace™ Rest API

The TopPlace™ Rest API allows the user to view all the popularity information offered by TopPlace™ in a more personalized way. Not only to visualize the data, but to also do internal analysis.

The data available from calls to the TopPlace™ Rest API includes:

  • Location Scores
  • Heat Maps
  • Nearby info
  • Points of Interest
  • Transport

In order to get the best results from the TopPlace™ Rest API, it is necessary to see how the data is generated.

What is GeoPopularity?

GeoPopularity is an algorithm developed by AVUXI as part of the TopPlace™ product. It is the underlying component of many of the calls available within the API. Depending on how GeoPopularity values are interpreted in relation to spatial information, different insights can be discovered about certain places.

The Geopoularity algorithm collates feedback information about a certain place from many different online media sources into a human understandable number to measure the popularity of that place.

It is important to understand that this algorithm will not indicate the most travelled or elitist venues, but rather, indicate s that have left a very positive impression on people.

For each place, the GeoPopularity algorithm generates a general Venue Score between 0 and 100, and a similar score for certain categories of social relevance. For example, we can find popular venues to visit, but not to eat, hence the importance of theses other scores.

The main objective of the GeoPopularity, is to provide a method of scoring the venues of any city by social category, for example nightlife, shopping, etc.

How does it work?

    The main steps are:
  • Discover relevant venues in different data sources.
  • Match venues from different sources into one data package.
  • Normalise the data with the data package to know what categories to assign to the venue and what is its exact location.
  • Extract the popularity data for each venue: total check-ins, total reviews, score, rating, etc.
  • Calculate scores and normalise them in relation to the city in values from 0 to 100: this gives us the Venue Score, which can now be saved on our database as a Point Of Interest.

With the previous steps our system created unique Points Of Interest (POIs) that are the base for all the processes within the TopPlace™ Rest API.

The Venue Score for each POI is used in the response for the majority of the requests to the TopPlace™ Rest API. Now we can look at the components for each request.


Components

In order to better understand a city and discover it quickly, we can use the Venue Score for a category (e.g. shopping) of all the venues in a city. With this data, we can generate different visualizations and discover the most relevant areas of a city for different categories.


Points of Interest

Points of Interest are the base for all our process, each Points of Interest has:
  • Name
  • Address
  • Coordinate
  • Venue Score
    • an individual score related to other POI’s in the city
    • a score for the main categories


Heat Maps

Heat Maps show the most relevant areas based on Venue Score concentration.

Darker areas on the map indicate places with greater concentrations of venues with high Venue Score for the chosen category.

Heat Maps can be create with tiles and vectors. This API only offers the vector version.

Location Scores

From a visual point of view, Heat Maps are easy to understand, yet the data they provide is not of great depth. In contrast, the Location Score gives us the popularity information at any point in a city based on the Venue Scores of nearby places. A Location Score is calculated for distances of 200m, 500, and 1500m. This gives users an idea of how relevant a place is if they are willing to walk 5, 10 or 15 minutes, respectively. For each distance a Location Score is given out of 100 for each category.

The aim of Location Score is to give an indication of how well located a place is in relevance to its immediate surroundings.

The Location Score can also be used to generate textual information about any point. This is the basis of Location Score Elements (discussed later).

The following images show Location Scores by category within the 3 radial distances of 200m, 500m, and 1500m from a location.

Below is an example of Location Scores calculated for a hotel near the Sagrada Familia and Plaza Cataluña.

One can easily see that for short walks from the hotel, luxury shopping appears to have a low score near to Sagrada Familia and very high in Plaza Cataluña area.

Areas of Interest

Areas of Interest are generated using criteria other than the aforementioned. The objective is to visualise cities in ways that people can immediately understand, see the below map for an example.

Areas of Interest can show which areas of a city are business areas, the city center, student zones, the beach, etc.

Whilst Location Score is used to discover popular places, the main objective of Areas of Interest is to describe a city with a common framework that can be applied to all the cities in the world. Thereby giving first time visitors to a city a quick overview of the social layout of a city.

Methods Available

GetLocationScoresByRadius

This request will return the Location Scores for a point specified in the parameters. The scores will be separated by radius and distance (200 m, 500 m and 1500m), with values for 0 - 99.


Parameters
NameFormatDescription
LatitudedoubleThe Latitude of the desired location
LongitudedoubleThe Longitude of the desired location

Example response:
{ "values": [ { "sights200": 99, "sights500": 99, "sights1500": 99, "eating200": 99, "eating500": 99, "eating1500": 99, "eatingvegetarian200": 81, "eatingvegetarian500": 99, "eatingvegetarian1500": 99, "shopping200": 99, "shopping500": 99, "shopping1500": 99, "shoppingluxury200": 70, "shoppingluxury500": 83, "shoppingluxury1500": 99, "nightlife200": 95, "nightlife500": 98, "nightlife1500": 99, "historical200": 99, "historical500": 99, "historical1500": 99, "beachpark200": 82, "beachpark500": 85, "beachpark1500": 90, "id": "0" } ], "state": 0, "note": "" }

HeatMap

This request returns polygon data that can be used to generate vector Heat Maps.

TopPlace™ Rest API can generate Heat Maps in Tiles (raster images) or Vectors. Currently, in this API we only offer the Vector version.

There are two methods of issuing this request:

GetHeatMapAvailableCategories

Return the list of categories available in one Tile at zoom 10 (see more about tiles).


Parameters
NameFormatDescription
tile10stringThe tile ID at zoom 10. E.g. 518_352 (T10 for Paris)

Example response:
{ "polygons": null, "categories": [ "phbeach", "phbeachpark", "phhistorical", "phpark", "phsights", "vnightlife", "vnightlifecasino", "vrestaurant", "vrestaurantfastfood", "vrestaurantvegetarian", "vshopping", "vshoppinglux" ], "state": 0, "note": "" }

GetHeatMapVectorial

Return the polygons for one category and Tile at zoom 10.


Parameters
NameFormatDescription
tile10 string The tile ID at zoom 10. E.g. 518_352 (T10 for Paris)
category string The category you wish to search. E.g. nightlife

Example response:
{ "polygons": { "levels": [ { "polygons": [ { "coords": [ [ 48.832294, 2.3176 ], [ ……… 48.862682, 2.343521 ] ], "title": "" } ], "level": "E" } ] }, "categories": null, "state": 0, "note": "" }

See Vector Map Integration for more details.


NearbyInfo

These methods offer location information about the surrounding area of a coordinate. It provides a more succinct summary of a location, such as:

  • The Location score for each category
  • Nearby POIs
  • Nearby Transport

All the methods return the same object.

GetLocationScore

Return the Location Score (0 to 99) for each category for the selected location.


Parameters
NameFormatDescription
LanguagestringThe ISO language code for your desired language
LatitudedoubleThe latitude of a location
LongitudedoubleThe longitude of a location

GetLocationScoreWithTop3Venues

Return the Score (0 to 99) for each category with top 3 venues near for the selected location.
Parameters
NameFormatDescription
LanguagestringThe ISO language code for your desired language
LatitudedoubleThe latitude of a location
LongitudedoubleThe longitude of a location

GetLocationScoreWithTop6Venues

Return the Score (0 to 99) for each category with top 6 venues near for the selected location.
Parameters
NameFormatDescription
LanguagestringThe ISO language code for your desired language
LatitudedoubleThe latitude of a location
LongitudedoubleThe longitude of a location

GetLocationScoreWithTop12Venues

Return the Score (0 to 99) for each category with top 12 venues near for the selected location.
Parameters
NameFormatDescription
LanguagestringThe ISO language code for your desired language
LatitudedoubleThe latitude of a location
LongitudedoubleThe longitude of a location

GetLocationScoreWithTop1ByCategory

Return the Score (0 to 99) for each category with top 1 venue by category for the selected location.
Parameters
NameFormatDescription
LanguagestringThe ISO language code for your desired language
LatitudedoubleThe latitude of a location
LongitudedoubleThe longitude of a location

GetNearbyTransport

Return the near metro stations for the selected location.
Parameters
NameFormatDescription
LanguagestringThe ISO language code for your desired language
LatitudedoubleThe latitude of a location
LongitudedoubleThe longitude of a location

PointsOfInterest

Methods to get POIs of interest to use in a map.

GetPointsOfInterestByBox

This request will return the points of interest within a specified bounding box.


Parameters
NameFormatDescription
NorthdoubleLatitude north of bounding box
WestdoubleLatitude west of bounding box
SouthdoubleLatitude south of bounding box
EastdoubleLatitude east of bounding box
LimitintegerLimit of POI’s to show. (defaults to 80)
LanguagestringISO Language code of language desired in the response

Example response:

{ "pois": [ { "latlon": [ 0 ], "name": "string", "cat": "string", "score": 0, "tags": [ "string" ] } ], "state": 0, "note": "string" }

Secure

GetSecureToken

Returns the key necessary to execute all the methods. Use this first. The key will be valid for 6 hours.


Parameters
NameFormatDescription
appidstringgets or sets the appid
appsecurestringgets or sets the appsecure

Example response:

{ "key": "string", "methods": [ "string" ], "state": 0, "note": "string" }

Transport

GetMetroLinesByCityCenter

Returns the metro lines and stops for the city related with the specified coordinate. Currently only works for selected cities.


Parameters
NameFormatDescription
LatitudedoubleThe latitude of a location
LongitudedoubleThe longitude of a location

See in action!

Next you can try all the methods. To obtain access you have to register and request access. Our team will analyze the use case and proceed to generate an access key to the API.

Appendix

Vector Map Integration

The Vector Maps are made up of polygons, which are themselves, graphical representations of location scores within the T10 specified in the parameters.

The Vector Map analyses the heat map and looks at the opacity of each pixel within the T10. Depending on the opacity, each pixel can be assigned to a different layer from A to E Pixels with the lowest opacity are assigned to A and pixels with the highest opacity are assigned to E.

The GetHeatMapVectorial call returns a list of polygons grouped into levels from A down to E.

These polygons can then be layered on top of each other to generate a heat map.

Below is a heat map made of layers B to E*. Layer B has the lowest threshold and therefore the broadest range. However only the best sightseeing opportunities will be within the area of polygons in Layer E (smaller and darker polygons). Therefore the amount of polygons in Layer E is much smaller.

*The threshold for level A is so low that generally it only makes sense to use it at a country level.

Example in JS

iOS Example

This example project can be used with the API (Vector Map Demo for iOS). The files have a similar structure.

What is a Tile?

How to get the data for the current map?

Our system saves the data by tiles at zoom 6 or zoom 10.

What is a tile? See this document: Map and Tile Coordinates.

In our map, we use the boundary of the map to calculate the tiles in this area.

Then load the polygons related with these tiles.

Tile at zoom 10 for Barcelona (tile x_y => 518_382)

Example in js.