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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
To find the hidden gems, where the "locals" go to, we have a special tag label frequented-by-locals,
best used in combination with another tag label. For instance if you are looking for restaurants frequented by the
people of Amsterdam:
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:
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:
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:
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:
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:
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:
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.
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:
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:
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:
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):
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:
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:
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:
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:
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:
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):
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:
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: