Triposo API Examples 20210615

How can I ...?

The examples on this page are intended to show how various common operations can be performed. If you still can't figure out how to do what you want, please contact [email protected] and let us know - we'll try to help you out!

Locations

Information about locations (cities, countries, islands, etc.) can be found using the location endpoint. Here's a simple example that retrieves all the information about a location with a known ID:

View the response

The following examples show how to find locations in various ways. (These examples limit the number of fields retrieved for each record, but that is simply for clarity.)

Find a country by name

Variations in spelling, etc. mean that trying to find a location by specifying an exact name is generally not a good idea. As a result, we recommend using the trigram similarity annotation when searching by name, and filter and sort as desired:

View the response

Note that this approach also works with a partial name, and so can be used for auto-completion in user-entry fields.

Find a city by name

The same approach can be used for finding cities (or other kinds of locations) by name:

View the response

One can also filter by the location ID of the country the city is in, if known:

View the response

Or exclude a given country:

View the response

Or filter by two-letter ISO country code:

View the response

Or by two-letter ISO U.S. state code:

View the response

Find the top cities in a country

If you have the location ID of a country then you can get a list of the top cities in that country:

View the response

If you don't have the country's location ID you can use its two-letter ISO country code instead:

View the response

Find main regions

For a given country, you can find the main regions it's divided into:

View the response

And for any of those, you can retrieve the best city within:

View the response

Find the top islands or nature reserves in a country

Similarly, you can find the top islands in a country:

View the response

Or the top national parks and nature reserves:

View the response

Find a location based on tags it contains

The returned objects will be automatically annotated with the tag score, which you can use in filtering or ordering. For example, to find the best locations for diving:

View the response

You can filter on multiple child tag labels and sort on their annotated scores.

View the response

Find other locations people visit

You can find which other locations are visited by people who visit a given location using the also_visited parameter. For example, suppose somebody is visiting Milan and you want to suggest other nearby places in Italy that they might like to visit. You could use a query like this:

View the response

This will return locations in Italy that are at most 300km from Milan, ordered by those most visited by people who also visited Milan. Each returned location is annotated with an also_visited_score field which indicates (roughly speaking) what fraction of people who have visited Milan have also visited this location.

Suppose the person has now returned home to France and you want to suggest other places to go based on their visit to Milan, but you don't want to suggest other places in Italy (they've just been there), nor places in France (their home country). This can be achieved with the following query:

View the response

Find locations by Musement location ID

You can find locations using Musement location IDs:

View the response

Points of interest

Information about POIs (sights, restaurants, hotels, etc.) can be found using the poi endpoint. Here's a simple example that retrieves all the information about a POI with a known ID:

View the response

You can retrieve information for multiple POIs in a single call if you know their IDs

View the response

The following examples show how to find POIs in various ways. (These examples limit the number of fields retrieved for each record, but that is simply for clarity.)

Find a POI by name

As with locations, the best way to search for a POI by name is to use the trigram similarity annotation and filter and sort as desired:

View the response

Of course, if you're looking for a POI in a particular location, it's best to restrict the search appropriately:

View the response

Find the top places to eat in a location

To find the best places in a location for a given tag label (see Finding tags), just specify the location ID and the tag label you want the place to have:

View the response

If you wish to find places with more than one tag label, you can specify multiple tag_labels parameters. You can also indicate that you want the POI to match (at least) one of a set of tag labels by separating them with a pipe symbol (|). For example, this will find the best places that are in either the City Center or Harbour districts of Sydney that also serve Italian cuisine:

View the response

You can also choose to sort by the POIs' scores for a given tag, which may differ from their main scores (a restaurant that is reasonably good overall might have excellent wines but terrible desserts; this would be reflected by the restaurant having a high wine score and low dessert score). The query shown above finds the best restaurants that happen to serve Italian food, even if the Italian food they serve is poor. The query below instead finds the places that are best for Italian food:

View the response

In a similar manner, it is possible to look for certain POIs that belong to a country. To do that, instead of restricting the search to a location, you can specify a two-letter ISO country code. For example, to look for beaches in Malta, you can specify Malta's country code:

View the response

If you're looking for POIs in the USA, you can specify a two-letter ISO U.S. state code instead of country code. For example, to get the top-5 kid friendly beaches in Hawaii:

View the response

POIs can belong to multiple locations

It is natural to consider a POI as belonging to more than one location. For example, the Brooklyn Museum is in New York City, but it is also on Long Island. It is also part of New York State and the United States of America, and thus can be found in the results when specifying any of these locations. For example:

View the response
View the response

Each POI has a single nominal location that is always returned in the location_id field regardless of any location specified as part of the query, but is otherwise not treated any differently to any other location a POI belongs to. A list of all the locations that a POI is considered part of can be obtained by requesting the location_ids field for the POI:

View the response

Note that this makes it easy to (for example) search for POIs on an island, without having to know which specific location they're in or iterating through the locations on the island to find everything. For example, to find things to see anywhere on Tenerife:

View the response

Find the hidden gems

To find the hidden gems, where the "locals" go to, you can use the tag label character-Popular_with_locals, best used in combination with another tag label. For instance if you are looking for restaurants popular with the people of Amsterdam:

View the response

Find places near given coordinates

POIs can also be queried based on their geospatial coordinates. For example, one can annotate POIs based on their distance from a given lat/long and then filter the results based on that distance. The following query finds all sightseeing POIs within 1km of a particular point in Bangkok:

View the response

The results can also be ordered based on the distance, for example to find the 10 closest places for something to eat:

View the response

A POI ID can be specified instead of a lat,lng coordinate, to use the coordinate of that POI. For example, to find the top 10 POIs for something to eat near Big Ben:

View the response

The distance annotation also supports geometries with multiple coordinates; currently multipoint (two or more disconnected points), linestring (a series of points forming a path) and polygon (an area outlined by a linestring). These can be specified as a series of lat,lng pairs (i.e. lat1,lng1,lat2,lng2,lat3,lng3,...), a list of POI IDs (to use the coordinates of those POIs) or a polyline encoded in the Google format.

To find the top places for something to eat within 100m of Duomo or Castello Sforzesco in Milan:

View the response

To find the top sightseeing POIs within 10km of a driving route from Amsterdam to Berlin (encoded in the Google polyline format):

View the response

To find the top POIs for nightlife within (i.e. distance=0 from) the Mitte district of Berlin, using a polygon to describe the district:

View the response

To find parking options nearby a hotel you are spending the night:

View the response

Find the places similar to places you know

You can also choose to find a place which is most like a place you know in your own hometown. The query below will find you the places most like Ippudo London in Amsterdam:

View the response

Find places that can be booked (hotels, museums, restaurants)

Certain POIs can be booked, via different vendors. The booking_info field provides more information (vendor, price, booking url). The following query finds the top bookable sightseeing POIs in Amsterdam:

View the response

Find POIs that do not have certain tags

You can specify ! before any tag label to exclude it. For example, to find the top POIs in Paris that are not sightseeing POIs:

View the response

Price tier information

We supply price tier information for POI's if available, 1=cheap, 2=medium, 3=expensive

View the response

Opening hours

You can get a structured representation of the opening hours for a Place of interest (where available).

View the response

Persona scores

We have released a beta versions of our persona based API querying. The idea of these personas is to add a user preference layer to the commonly used tags. The current predefined personas for interest are quite self explanatory namely food_lover, culture_buff, nature, shopper and party. They are best used in conjunction with tag labels as can be illustrated with the help of this example:

View the response

We have also have personas for budget (budget, mid_range, splurge):

View the response

and composition (family, couples):

View the response

Find POIs by Musement venue ID

You can find POIs using their Musement venue ID:

View the response

Tags

Information about tags can be found using the tag and common_tag_labels endpoints.

Note that the Triposo API distinguishes between tags and tag labels. Tags are always specific to a particular location, and include score and other information. Tag labels are ways to identify particular tags, and often apply across locations. For example, the tag label eatingout can be used to find the tag for eating out in any location that has such a tag (most do). Note also that in any given location there is at most one tag with a given tag label: the combination of location ID and tag label uniquely identifies a tag.

Common tag labels can be obtained through the common_tag_labels endpoint; these are also listed in the reference documentation. Other tag labels can be obtained by querying the tag or other endpoints.

To continue the example, here's how to retrieve all the information about the tag in Florence that has the eatingout label:

View the response

The following examples show how to find tags and tag labels in various ways.

Find the top-scoring tags for a location

To obtain tags without using a known tag label, you can query the tag endpoint. For example, you can find the top-scoring tags in a given location like this:

View the response

It is also possible to filter out tags about which there are tours available, for a given location:

View the response

Or there is at least a certain number of POIs that are assigned this tag:

View the response

Or see the tags that have articles assigned to them for a certain location:

View the response

Find all tags of a given type in a location

Tags are organised into a hierarchy, and can be queried based on that hierarchy. Thus you can find all cuisine-related tags in a city, for example, by querying for all the tags in that city that have a tag labelled cuisine as an ancestor:

View the response

If a POI belongs to a given tag, it will also belong to all of that tag's ancestors. Also note that some tags have more than one direct parent. For example, the tag for water parks (poitype-Water_park) has parents swimming and amusementparks, since water parks are relevant for both.

Below are more examples of finding various kinds of tags using the tag hierarchy. To find all districts in a location:

View the response

Or all architecture-related tags:

View the response

Or all tags related to practicalities:

View the response

Or all person-related tags:

View the response

More ways to find tags using the tag hierarchy

Some tags are considered "internal", meaning that they're not normally relevant to show to end users. The cuisine tag is an example of such a tag: it is not normally interesting to know that a POI belongs to such a tag, or to find all POIs belonging to it. Such tags, however, are useful for finding more-specific related tags like in the above examples.

By default, the tag endpoint does not return internal tags. You can get the internal tags by specifying internal=true:

View the response

If you want all tags, whether they're internal or not, you can specify a wildcard (*) as the value for the internal parameter:

View the response

In the previous section we showed how to find all tags that were descendants of a given tag label (by requesting tags that had that label as an ancestor). It is also possible to find the ancestors of a given tag (by requesting tags that have that label as a descendant):

View the response

Or just the direct parents:

View the response

Or just the direct children:

View the response

Find all tags for a district

To obtain the tags that are relevant for a certain district in a location you can use the related_labels parameter of the tag endpoint. For example, you can find all the tags in "The Rocks" in Sydney:

View the response

Tours

Information about tours can be found using the tour endpoint. Here's a simple example that retrieves all the information about a tour with a known ID:

View the response

The following examples show how to find tours in various ways. (These examples limit the number of fields retrieved for each record, but that is simply for clarity.)

Find top tours in a location

To find tours in a location, just specify the location ID when calling the tour endpoint (note that some tours can belong to more than one location):

View the response

Similarly, you can find tours for a country, if querying by a two-letter ISO country code instead of a location:

View the response

Or, for the USA, a two-letter ISO U.S. state code:

View the response

You can also filter and order by price by converting prices to the desired currency:

View the response

And of course you can filter based on tag labels:

View the response

Find tours for a given POI

You can find the tours for a given POI by providing the POI ID to the tour endpoint:

View the response

Persona scores

We have released a beta versions of our persona based API querying. The idea of these personas is to add a user preference layer to the commonly used tags. The current predefined personas for interest are quite self explanatory namely food_lover, culture_buff, nature, shopper and party.

View the response

We have also have personas for budget (budget, mid_range, splurge):

View the response

and composition (family, couples):

View the response

Articles

Information about articles (further reading related to locations and the like) can be found using the article endpoint. Here's a simple example that retrieves all the information about an article with a known ID:

View the response

The text in the articles is marked up with references to POIs, locations, other articles, etc. where relevant, providing a way to support convenient navigation to things referenced in the text.

The following examples show how to find articles in various ways. (These examples limit the number of fields retrieved for each record, but that is simply for clarity.) Articles are commonly also found via references in other articles.

Find articles for a location with a given tag

You can find all the articles for a location with a given tag label simply by giving the location ID and the tag label. For example, to find all food-related articles for Jakarta:

View the response

Instead of location, it is also possible to get all articles for a country:

View the response

Or a US state:

View the response

Or to find all wildlife-related articles for Botum Sakor National Park:

View the response

We also allow to search for articles about artworks using the poi_id of the museum:

View the response

or the other way around where you want to know the museum an artwork is connected to:

View the response

The articles can also be filtered by their type:

View the response

City walks

Creating a city walk for a city can be done using the city_walk endpoint. Here's a simple example that creates a city walk for Prague:

View the response

You can customize your city walk by giving it a custom starting point and specifying a tag label:

View the response

Or customize further by including (or excluding) a specific place of interest and specifying that you want to include visiting time (go_inside).

View the response

You can also exclude tag labels, for instance if you don't want to include dinner places.

View the response

Local highlights

Creating a set of local highlights near a certain coordinate can be done using the local_highlights endpoint. Here's a simple example that finds the local highlights near Ipanima beach in Rio de Janeiro:

View the response

You can customize the resulting pois by restricting them to certain tag labels:

View the response

If your accommodation is in a quiet area, see what's out there in a 8km radius.

View the response

Day planner

Finding a plan with things to do for several days in a city can be done using the day_planner endpoint. Here's a simple example that creates a day plan for 3 days in Lisbon:

View the response

Instead of a hotel as a starting point, one can ask for a day plan based on the coordinates of a starting point. A preferred distance between itinerary items can also be specified:

View the response

If you want a more relaxed (or faster-paced) plan, you can specify how many things per day you would like to do:

View the response

Local scores

Finding how suitable a certain place is with respect to a set of tag labels (sightseeing, eating out, nightlife and shopping) can be done using the local_score endpoint. Multiple points can be queried with a single API call by specifying the coordinates parameter multiple times. Here's a simple example that shows these scores for two places (Forum Romanum in Rome and the Wallen in Amsterdam):

View the response

Properties

If you already know the id of a POI and you only need certain information, such as its phone, its website, or similar, you can ask for those properties through the property endpoint:

View the response

If it is a specific property that you are looking for, you can specify that property's key. To get the phone number of the Eiffel tower, the query would be:

View the response

Similarly, one can get the listed properties of a location:

View the response

Common tag labels

Finding a list of all common tag labels can be done using the common_tag_labels endpoint. Here's the call to get the complete list:

View the response