Triposo API Documentation - 20181213

Request/response format

Requests to the API should be made as an HTTPS GET to a URL in the following format: 

https://www.triposo.com/api/20181213/endpoint.json?parameters

The response in the case of success will be JSON in the following format:

{
  "results": [an array of objects according to the return type of the endpoint],
  "estimated_total": the estimated number of total objects,
  "more": true if there are more objects that could be retrieved using a higher offset or a larger count
}

In case of an error, an appropriate HTTP error code will be set and the body of the response will be JSON in the following format:

{
  "code": an error code,
  "error": a string explaining the error
}

Authentication information can either be supplied as account and token parameters, containing your account ID and a valid token respectively, or using the X-Triposo-Account and X-Triposo-Token HTTP headers.

Endpoints

article /api/20181213/article.json Credit cost 1

retrieve article about a subject

Return type

article

Parameters

Name Query type Required? Default value Description
annotate exact no add a value to each returned object; possible annotations are defined on each model
count exact no 10 the maximum number of objects to return (max: 100)
countrycode exact no select objects within a country specified by two-letter ISO country code
exclude_fields exact no a comma-separated list of fields not to return, either from the default fields or from all fields if fields=all is specified
fields exact no a comma-separated list of fields to return, or "all" to return all fields
id exact_negatable no the machine-readable identifier for this article
language exact no en set preferred language
location_ids contains_location no the locations that this article applies to
offset exact no 0 the index of the object in the result set to start from
order_by exact no the field to order the results by (the field must be orderable). for reverse order prefix the field name with "-"
poi_id exact no retrieving related articles by specifying one or more POI IDs, for now only applicable to museums and articles about artworks
score range no an indicator of the importance of the article, generally between 0 and 10 but best suited to relative comparisons and ordering
tag_labels contains_tag no the labels of the tags that apply to this article
type exact_negatable no the type of the article
us_statecode exact no select objects specified by two-letter US state code

Possible values for 'type'

animal articles about animals
art articles about works of art
background background articles
cuisine articles about dishes and cuisines
festival articles about festivals
language_description main articles about a language
language_phrasebook articles containing a phrasebook for a language
language_pronunciation articles about the pronunciation of a language

city_walk /api/20181213/city_walk.json Credit cost 12

create a city walk for a certain city

Return type

city_walk

Parameters

Name Query type Required? Default value Description
exclude_poi_fields exact no a comma-separated list of fields not to return, either from the default fields or from all fields if poi_fields=all is specified
exclude_poi_ids exact no a comma-separated list of ids of the POIs you do not want to include in the city walk
go_inside exact no True boolean to decide if you want to enter the POIs encountered en route, default true
include_poi_ids exact no a comma-separated list of ids of the POIs you want to include in the city walk
latitude exact no latitude of starting point
location_id exact yes the id of the city for which you want to create a walk
longitude exact no longitude of the starting point
optimal exact no false boolean to only use the top POIs in the city, default false. When true no random factor is used in the calculation
poi_fields exact no a comma-separated list of return fields for the POI objects
seed exact no unsigned integer used for seeding a random factor in the creation of the city walk. It can be used to retrieve specific past responses
tag_labels contains_tag no only include POIs matching these tag labels (otherwise all are included). use | for OR and ! for NOT. for AND, specify the parameter multiple times
total_time exact yes maximum length of the city walk in minutes. (min=20 max=360)
type exact no sightseeing type of city walk (sightseeing, pub_crawl), default sightseeing (deprecated - use tag_labels instead)

common_tag_labels /api/20181213/common_tag_labels.json Credit cost 0

retrieves list of common tag labels that can be used to filter API responses

Return type

common_tag_label

Parameters

Name Query type Required? Default value Description
annotate exact no add a value to each returned object; possible annotations are defined on each model
countrycode exact no select objects within a country specified by two-letter ISO country code
exclude_fields exact no a comma-separated list of fields not to return, either from the default fields or from all fields if fields=all is specified
fields exact no a comma-separated list of fields to return, or "all" to return all fields
language exact no en set preferred language
order_by exact no the field to order the results by (the field must be orderable). for reverse order prefix the field name with "-"
us_statecode exact no select objects specified by two-letter US state code

day_planner /api/20181213/day_planner.json Credit cost 10

produce an itinerary for one or more days for a particular location

Return type

day_plan

Parameters

Name Query type Required? Default value Description
arrival_time exact no 08:00 the arrival time on the first day in HH:MM format
departure_time exact no 22:00 the departure time on the last day in HH:MM format
end_date exact no the date of the last day of the itinerary in YYYY-mm-dd format (default is the day after start_date)
hotel_poi_id exact no the optional POI ID of the hotel, to plan the day(s) around staying at this hotel
items_per_day exact no 4 how many sightseeing items to include in the itinerary per day
latitude exact no the latitude of the location to plan the day(s) around (leave blank if hotel_poi_id is specified)
location_id exact yes the ID of the location to plan day(s) in
longitude exact no the longitude of the location to plan the day(s) around (leave blank if hotel_poi_id is specified)
max_distance exact no 500 the preferred maximum distance in metres for the itinerary to travel from one POI to another POI
seed exact no unsigned integer used for seeding a random factor in the creation of the day plan. It can be used to retrieve specific past responses
start_date exact no the date of the first day of the itinerary in YYYY-mm-dd format (default is today)

local_highlights /api/20181213/local_highlights.json Credit cost 8

create a optimized set of POIs centered around a coordinate, the resulting POIs are annotated with distance to the coordinate

Return type

local_highlights

Parameters

Name Query type Required? Default value Description
exclude_poi_fields exact no a comma-separated list of fields not to return, either from the default fields or from all fields if poi_fields=all is specified
latitude exact yes latitude of center point
longitude exact yes longitude of center point
max_distance exact no 700 maximum distance in meters to the center point for the POIs, default 700 meters
poi_fields exact no a comma-separated list of return fields for the POI objects
tag_labels contains_tag no only include POIs matching these tag labels (otherwise all are included). use | for OR and ! for NOT. for AND, specify the parameter multiple times

local_score /api/20181213/local_score.json Credit cost 10

calculate local scores for a set of coordinates

Return type

local_score

Parameters

Name Query type Required? Default value Description
coordinates exact yes coordinates of the points for which the local score will be calculated (latitude,longitude), parameter can be specified up to 10 times

location /api/20181213/location.json Credit cost 2

retrieve information about locations such as cities and countries

Return type

location

Parameters

Name Query type Required? Default value Description
also_visited exact no selects locations that are also visited by people who visit the location specified by this parameter. Adds a field "also_visited_score" with value 0..1 to each returned location, indicating how likely it is that a person who has visited the specified location has also visited the returned location
annotate exact no add a value to each returned object; possible annotations are defined on each model
child_tag_labels contains_tag no filter based on the labels of tags contained within this location
count exact no 10 the maximum number of objects to return (max: 100)
countrycode exact no select objects within a country specified by two-letter ISO country code
exclude_fields exact no a comma-separated list of fields not to return, either from the default fields or from all fields if fields=all is specified
fields exact no a comma-separated list of fields to return, or "all" to return all fields
id exact_negatable no the machine-readable identifier for the location
language exact no en set preferred language
musement_locations exact no list of musement locations associated to this location
offset exact no 0 the index of the object in the result set to start from
order_by exact no the field to order the results by (the field must be orderable). for reverse order prefix the field name with "-"
parent_id exact_negatable no the ID of the parent location
part_of exact_negatable no retrieve locations that are part of a location specified by location ID
score range no an indicator of the importance of the location, generally between 0 and 10 but best suited to relative comparisons and ordering
tag_labels contains_tag no the labels of the tags that apply to this location
type exact_negatable no the general type of this location
us_statecode exact no select objects specified by two-letter US state code

Annotations

Name Description Result type Result query type Result orderable? Result nullable? Annotates the score?
distance annotate each result object with its distance in metres from a specified point or line integer range True False False
 

Syntax:

annotate=distance:[a point as decimal latitude,longitude, or a line as a sequence of decimal latitude,longitude pairs separated by commas, or a polyline encoded in the Google format]
trigram annotate each result object with the trigram similarity (0..1) of its name to a string float range True False False
 

Syntax:

annotate=trigram:[string to compare the name field to]

Possible values for 'type'

city a city
city_state a city-state
country a country
island an island
national_park a national park
region a region

poi /api/20181213/poi.json Credit cost 2

retrieve information about points of interest

Return type

poi

Parameters

Name Query type Required? Default value Description
annotate exact no add a value to each returned object; possible annotations are defined on each model
bookable exact no specifying a value of 1 or true restricts results to bookable POIs
count exact no 10 the maximum number of objects to return (max: 100)
countrycode exact no select objects within a country specified by two-letter ISO country code
exclude_fields exact no a comma-separated list of fields not to return, either from the default fields or from all fields if fields=all is specified
fields exact no a comma-separated list of fields to return, or "all" to return all fields
has_similarity exact no specifying a value of 1 or true restricts results to POIs that have a similarity dimension, i.e. that can be used for similarity queries
id exact_negatable no the machine-readable identifier of this POI
language exact no en set preferred language
location_id exact_negatable no the ID of the location this POI is contained within
musement_venue_id exact_negatable no Musement venue identifier for this POI
offset exact no 0 the index of the object in the result set to start from
order_by exact no the field to order the results by (the field must be orderable). for reverse order prefix the field name with "-"
score range no an indicator of the importance of this POI, generally between 0 and 10 but best suited to relative comparisons and ordering
tag_labels contains_tag no the labels of the tags that apply to this POI
us_statecode exact no select objects specified by two-letter US state code

Annotations

Name Description Result type Result query type Result orderable? Result nullable? Annotates the score?
distance annotate each result object with its distance in metres from a specified point or line integer range True False False
 

Syntax:

annotate=distance:[a point as decimal latitude,longitude, or a line as a sequence of decimal latitude,longitude pairs separated by commas, or a polyline encoded in the Google format]
persona annotate each object with the persona specific score with the property name persona_xxx_score float range True False True
 

Syntax:

annotate=persona:[name of persona (budget, mid_range, splurge, food_lover, culture_buff, nature, party, shopper, family, couples) for which to add a score]
similarity annotate each object with the similarity score (-1..1) compared with the given object float range True True False
 

Syntax:

annotate=similarity:[id of the object with which the comparison is made]
trigram annotate each result object with the trigram similarity (0..1) of its name to a string float range True False False
 

Syntax:

annotate=trigram:[string to compare the name field to]

property /api/20181213/property.json Credit cost 1

retrieve information about metadata relating to locations, POIs or tours

Return type

property

Parameters

Name Query type Required? Default value Description
annotate exact no add a value to each returned object; possible annotations are defined on each model
count exact no 10 the maximum number of objects to return (max: 100)
exclude_fields exact no a comma-separated list of fields not to return, either from the default fields or from all fields if fields=all is specified
fields exact no a comma-separated list of fields to return, or "all" to return all fields
key exact_negatable no a machine-readable identifier for this property (unique for the POI, tour or location that the property relates to)
language exact no en set preferred language
location_id exact_negatable no the ID of the location this property applies to, if it applies to one
offset exact no 0 the index of the object in the result set to start from
order_by exact no the field to order the results by (the field must be orderable). for reverse order prefix the field name with "-"
poi_id exact_negatable no the ID of the POI this property applies to, if it applies to one
tour_id exact_negatable no the ID of the tour this property applies to, if it applies to one

source /api/20181213/source.json Credit cost 0

retrieve information about sources and the way to attribute them

Return type

source

Parameters

Name Query type Required? Default value Description
id exact no the machine-readable identifier of the source

tag /api/20181213/tag.json Credit cost 2

retrieve information about tags and the tag labels that correspond to POIs, tours and articles

Return type

tag

Parameters

Name Query type Required? Default value Description
annotate exact no add a value to each returned object; possible annotations are defined on each model
article_count range no the number of articles that have this tag
count exact no 10 the maximum number of objects to return (max: 100)
countrycode exact no select objects within a country specified by two-letter ISO country code
exclude_fields exact no a comma-separated list of fields not to return, either from the default fields or from all fields if fields=all is specified
fields exact no a comma-separated list of fields to return, or "all" to return all fields
label exact_negatable no a machine-readable label for this tag - only unique within a location_id
language exact no en set preferred language
location_id exact_negatable no the ID of the location this tag applies to
offset exact no 0 the index of the object in the result set to start from
order_by exact no the field to order the results by (the field must be orderable). for reverse order prefix the field name with "-"
poi_count range no the number of POIs that have this tag
related_labels exact no filter tags based on overlap in POIs, locations, articles or tours with other tags
score range no the score of this tag, between 0 and a bit more than 10
tour_count range no the number of tours that have this tag
type exact_negatable no the general type of this tag
us_statecode exact no select objects specified by two-letter US state code

Possible values for 'type'

architecture tags for specific architecture types such as Gothic, Buddhist, etc.
background background articles on things such as culture, art, history and visa information
badge options like wifi, family-friendly, etc.
cuisine cuisines and dishes
district districts within a city
do_and_see sightseeing-related tags
hotel_proximity special type that reports access to top POIs across categories such as eatingout, shopping and sightseeing from a hotel
meals_and_refreshments popular meals such as lunch, dinner, breakfast, coffee and drinks
person related to a person of note
practical safety, health, money and transport information
sleep hotels and other places to sleep
tour_itinerary tags that indicate the places tours visit
tours related to tours
world tags defining geographical relationships between locations - e.g. which locations are part of a given country, region, etc.

tour /api/20181213/tour.json Credit cost 1

retrieve information about bookable tours

Return type

tour

Parameters

Name Query type Required? Default value Description
annotate exact no add a value to each returned object; possible annotations are defined on each model
count exact no 10 the maximum number of objects to return (max: 100)
countrycode exact no select objects within a country specified by two-letter ISO country code
exclude_fields exact no a comma-separated list of fields not to return, either from the default fields or from all fields if fields=all is specified
fields exact no a comma-separated list of fields to return, or "all" to return all fields
id exact_negatable no the machine-readable identifier of this tour
language exact no en set preferred language
location_ids contains_location no the locations that this tour is related to
offset exact no 0 the index of the object in the result set to start from
order_by exact no the field to order the results by (the field must be orderable). for reverse order prefix the field name with "-"
poi_id exact no retrieve tours associated with this POI ID. if no order_by is specified, tours will be ordered by their relevance to that POI (most relevant first)
price_is_per_person exact no if true, it means that the price is the same for each person going on the tour. if false, it usually means that the prices for the second, third, etc. people are discounted in some way
score range no an indicator of the importance of this tour, generally between 0 and 10 but best suited to relative comparisons and ordering
tag_labels contains_tag no the labels of the tags that apply to this tour
us_statecode exact no select objects specified by two-letter US state code
vendor exact_negatable no the vendor offering this tour (viator, withlocals, bemyguest, tiqets, musement)

Annotations

Name Description Result type Result query type Result orderable? Result nullable? Annotates the score?
converted_price annotate each object with its price converted into a specified currency price range True False False
 

Syntax:

annotate=converted_price:[currency to convert the price to]
persona annotate each object with the persona specific score with the property name persona_xxx_score float range True False True
 

Syntax:

annotate=persona:[name of persona (budget, mid_range, splurge, food_lover, culture_buff, nature, party, shopper, family, couples) for which to add a score]
trigram annotate each result object with the trigram similarity (0..1) of its name to a string float range True False False
 

Syntax:

annotate=trigram:[string to compare the name field to]

Types

article

longer-form content related mostly to information about a location or a tag but could also be about works of art, composers etc.

Name Type Description Orderable? Included by default? May be null? I18n?
content content the content of this article no yes no no
id string the machine-readable identifier for this article no yes no no
intro string a medium-length version of the content of this article no no yes yes
intro_language_info language_info information regarding the language of intro no no yes no
location_ids string[] the locations that this article applies to no no no no
name string a human-readable title for this article no yes no yes
name_language_info language_info information regarding the language of name no yes yes no
pois poi[] POIs associated with this article, for now only museums associated with an artwork no no no no
score float an indicator of the importance of the article, generally between 0 and 10 but best suited to relative comparisons and ordering yes yes no no
snippet string a short version of the content of this article no yes yes yes
snippet_language_info language_info information regarding the language of snippet no yes yes no
structured_content structured_content the structured content of this article (no machine translation) no yes no yes
structured_content_language_info language_info information regarding the language of structured_content no yes yes no
tag_labels string[] the labels of the tags that apply to this article no no no no
tags tag_with_score[] the full tags that apply to this article no no no no
type article_type the type of the article no no no no

article_type

the general type of an article

attribution

attribution information for a specific piece of content

Name Type Description Orderable? Included by default? May be null? I18n?
source_id string the ID of the source no yes no no
url string the URL for this content at the source no yes yes no

booking_info

information describing a bookable object

Name Type Description Orderable? Included by default? May be null? I18n?
price price the cost of booking this object no yes yes no
vendor vendor_identifier the vendor of this object (tour / hotel / restaurant) no yes no no
vendor_object_id string the ID of this object in the vendor's system no yes no no
vendor_object_url string the URL of this object on the vendor's website no yes no no

boolean

"true" or "false"

city_walk

a city walk for a certain city

Name Type Description Orderable? Included by default? May be null? I18n?
seed integer seed used to generate this city walk no yes yes no
total_duration integer estimated duration of the city walk in minutes no yes no no
walk_distance integer estimated length of the city walk in meters no yes no no
walk_duration integer estimated duration of the walking part of the city walk in minutes no yes no no
way_points way_point[] no yes no no

common_tag_label

common tag label used for filtering

Name Type Description Orderable? Included by default? May be null? I18n?
description string description of the tag label in question no yes yes no
id string id of the tag label in question no yes no no
name string name of the tag label in question no yes no no

content

content, including attribution information

Name Type Description Orderable? Included by default? May be null? I18n?
attribution attribution[] the attribution needed for this content no yes no no
sections section[] the sections of this content no yes no no
title string title of this content no yes no no

day_plan

a planned itinerary for several days spent in a location

Name Type Description Orderable? Included by default? May be null? I18n?
days itinerary[] day by day description of the day plan no yes no no
hotel poi hotel description where the day plan is based from, if supplied no yes yes no
location location location in which the walk takes place no yes no no
seed integer seed used to generate this dayplan no yes yes no

day_time

a description of a time in hours and minutes

Name Type Description Orderable? Included by default? May be null? I18n?
hour integer number of hours of the time (24 hours based) no yes no no
minute integer number of minutes of the time no yes no no

duration_unit

the units of a duration

float

a floating-point number

image

an image, including metadata

Name Type Description Orderable? Included by default? May be null? I18n?
attribution image_attribution attribution information for this image no yes no no
caption string a suitable caption for this image no yes yes no
license string the identifier of the license for this image (deprecated - use attribution field instead) no yes yes no
owner string the copyright owner of this image (deprecated - use attribution field instead) no yes no no
owner_url string the URL for the copyright owner of this image (deprecated - use attribution field instead) no yes no no
sizes image_sizes the available sizes for this image no yes no no
source_id string the ID of the source for this image no yes no no
source_url string where the image was found on the Web no yes no no

image_attribution

attribution information for an image

Name Type Description Orderable? Included by default? May be null? I18n?
attribution_link string the URL which the attribution text should link to no yes no no
attribution_text string text to display in order to properly attribute the image no yes no no
format string the format in which to attribute. The following substitutions need to be made: {attribution} needs to be substituted by the attribution_text and needs to link to the attribution_link URL, {license} needs to be substituted by the license_text and needs to link to the license_link URL, if license_link is set no yes no no
license_link string the URL which the license text should link to no yes yes no
license_text string the license text to display for the image no yes yes no

image_format

the format of an image

image_size

metadata for a particular size of an image

Name Type Description Orderable? Included by default? May be null? I18n?
bytes integer size of image in bytes no yes no no
format image_format the format of the image no yes no no
height integer height of image no yes no no
url string url for image no yes no no
width integer width of image no yes no no

image_sizes

available sizes for an image

Name Type Description Orderable? Included by default? May be null? I18n?
medium image_size image with largest dimension up to 640 pixels no yes yes no
original image_size image in its original size no yes no no
thumbnail image_size image with largest dimension up to 192 pixels no yes no no

integer

an integer

itinerary

a planned itinerary for a day spent in a location

Name Type Description Orderable? Included by default? May be null? I18n?
date string the date that the itinerary is for, in YYYY-mm-dd format no yes no no
itinerary_items itinerary_item[] the items of the itinerary for this date no yes no no

itinerary_item

an item on a planned itinerary

Name Type Description Orderable? Included by default? May be null? I18n?
description string a longer description of this itinerary item no yes no no
poi poi the POI object corresponding to this itinerary item no yes no no
title string a title for this itinerary item no yes no no

language_code

two-letter language code

language_info

information about translated content

Name Type Description Orderable? Included by default? May be null? I18n?
language language_code the language the returned content is in (not necessarily requested language, if translation was not performed) no yes no no
original_language language_code the original language of the content no yes no no
translation_provider translation_provider the provider used for translation, if translation was performed no yes yes no

local_highlights

a local guide centered around a lat/lng

Name Type Description Orderable? Included by default? May be null? I18n?
poi_division poi_division_element[] which POIs were selected for which tag_labels no yes no no
pois poi[] POIs which are local highlights, annotated with distance to specified point no yes no no

local_score

the local score for a given set of tag labels

Name Type Description Orderable? Included by default? May be null? I18n?
coordinates point coordinate of the point for which the scores are calculated no yes no no
scores tag_label_with_score[] list of local scores per tag_label no yes no no

location

describes cities, countries, islands, national parks and regions

Name Type Description Orderable? Included by default? May be null? I18n?
attribution attribution[] information about the sources this content came from no yes no no
content content content describing this location no no yes no
coordinates point a point representing the geographical position of the location no yes no no
country_id string the location ID of the country this location is contained within no yes no no
id string the machine-readable identifier for the location no yes no no
images image[] images of this location no yes no no
intro string a medium-length string describing the location no no yes yes
intro_language_info language_info information regarding the language of intro no no yes no
musement_locations musement_location[] list of musement locations associated to this location no no no no
name string the human-readable name of the location (in user's language where possible) yes yes no yes
parent_id string the ID of the parent location no yes yes no
properties property[] the properties related to this location no no no no
public_transport_maps image[] public transport maps for this location (currently available only for select cities) no no no no
score float an indicator of the importance of the location, generally between 0 and 10 but best suited to relative comparisons and ordering yes yes no no
snippet string a short string describing the location no yes yes yes
snippet_language_info language_info information regarding the language of snippet no yes yes no
structured_content structured_content structured content describing this location (no machine translation) no no yes yes
structured_content_language_info language_info information regarding the language of structured_content no no yes no
tag_labels string[] the labels of the tags that apply to this location no no no no
tags tag_with_score[] the full tags that apply to this location no no no no
type location_type the general type of this location no yes no no

location_type

the general type of a location

musement_location

describes a Musement location

Name Type Description Orderable? Included by default? May be null? I18n?
district_tag string optional tag to identify a district/suburb inside the Triposo location that this Musement location is referring to no yes yes no
location_id string the ID of the Triposo location associated to this Musement location no yes no no
musement_id string the ID of the Musement location no yes no no
name string the name of the Musement location no yes no no

opening_hours

structured representation of opening hours

Name Type Description Orderable? Included by default? May be null? I18n?
days time_ranges_by_day collection of days with the information about the time ranges on that day no yes no no
open_24_7 boolean boolean indicating if a POI is open 24/7 no yes no no

poi

points of interest

Name Type Description Orderable? Included by default? May be null? I18n?
attribution attribution[] information about the sources this content came from no yes no no
best_for tag[] the tags for which this POI is best within the location no no no no
booking_info booking_info information needed to book this POI (whether it's a hotel, a place that has entrance tickets, or a restaurant) no yes yes no
content content content related to this POI no no yes no
coordinates point the geographical location of this POI no yes no no
facebook_id string Facebook identifier for this POI no no yes no
id string the machine-readable identifier of this POI no yes no no
images image[] images of this POI no yes no no
intro string a medium-length version of the content no no yes yes
intro_language_info language_info information regarding the language of intro no no yes no
location_id string the ID of the location this POI is contained within no yes no no
musement_venue_id string Musement venue identifier for this POI no no yes no
name string the human-readable name of this POI yes yes no yes
opening_hours opening_hours a structured description of the opening hours on a normal week (public holidays and such are not taken into account) no no yes no
price_tier integer price indication for this POI, if available. 1=cheap, 2=medium, 3=expensive no yes yes no
properties property[] the properties related to this POI no no no no
score float an indicator of the importance of this POI, generally between 0 and 10 but best suited to relative comparisons and ordering yes yes no no
snippet string a short version of the content no yes yes yes
snippet_language_info language_info information regarding the language of snippet no yes yes no
structured_content structured_content structured content related to this poi (no machine translation) no no yes yes
structured_content_language_info language_info information regarding the language of structured_content no no yes no
tag_labels string[] the labels of the tags that apply to this POI no no no no
tags tag_with_score[] the full tags that apply to this POI no no no no

poi_division_element

a tag label/POI ids structure to specify one element of the local highlights POI division

Name Type Description Orderable? Included by default? May be null? I18n?
poi_ids string[] POI ids of belonging to this tag label no yes no no
tag_label string the best tag label for the POIs specified no yes no no
tag_name string human readable name for the tag label no yes no no

point

a point on Earth

Name Type Description Orderable? Included by default? May be null? I18n?
latitude float the latitude of the point no yes no no
longitude float the longitude of the point no yes no no

price

a price, including currency information

Name Type Description Orderable? Included by default? May be null? I18n?
amount string the amount as a decimal string no yes no no
currency string the three-digit ISO currency code no yes no no

property

key/value pairs associated with POIs, tours or locations

Name Type Description Orderable? Included by default? May be null? I18n?
key string a machine-readable identifier for this property (unique for the POI, tour or location that the property relates to) no yes no no
location_id string the ID of the location this property applies to, if it applies to one no no yes no
name string a human-readable name for the property no yes no no
ordinal integer the position of this property in a natural ordering of the properties applying to this POI/tour/location yes yes no no
poi_id string the ID of the POI this property applies to, if it applies to one no no yes no
tour_id string the ID of the tour this property applies to, if it applies to one no no yes no
value string the human-readable value of the property no yes no no

section

a section of a content object

Name Type Description Orderable? Included by default? May be null? I18n?
body string the content of this section, as HTML. References to objects in our database are represented using <a> tags with data-* attributes specifying which object it is. data-object_type gives the object type / endpoint (e.g. poi) and data-id gives the ID of the object no yes yes no
image image an image related to this section no yes yes no
title string the title of this section no yes yes no

source

general information about a data source

Name Type Description Orderable? Included by default? May be null? I18n?
attribution_text string text to display in order to properly attribute the content no yes yes no
format string the format in which to attribute. The following substitutions need to be made: {attribution} needs to be substituted by the attribution_text and needs to link to the url specified in the url field in the corresponding attribution record, {license} needs to be substituted by the license_text and needs to link to license_link, if license_link is set no yes no no
id string a machine-readable identifier for the source no yes no no
license_link string the URL which the license text should link to no yes yes no
license_text string the license text to display no yes yes no

string

a string

structured_content

structured content, including attribution information

Name Type Description Orderable? Included by default? May be null? I18n?
attribution attribution[] the attribution needed for this content no yes no no
images image[] images for this content no yes no no
sections structured_content_section[] the sections of this content no yes no no

structured_content_section

a section of a structured_content object

Name Type Description Orderable? Included by default? May be null? I18n?
body string the content of this section, as HTML. References to objects in our database are represented using <a> tags with data-* attributes specifying which object it is. data-object_type gives the object type / endpoint (e.g. poi) and data-id gives the ID of the object. References to images are represented using <img> tags, with data-index specifying the (0-offset) index into the list of images for the structured_content and data-caption optionally specifying a caption for the image no yes yes no
labels string[] a list of labels for this section no yes no no
sections structured_content_section[] a list of subsections no yes no no
summary string a shorter summary of this section (not present if body is already short enough) no yes yes no
title string the title of this section no yes yes no

tag

describes a tag and shows how many POIs/tours/articles have this tag

Name Type Description Orderable? Included by default? May be null? I18n?
article_count integer the number of articles that have this tag yes yes no no
content content content related to this tag no no yes no
label string a machine-readable label for this tag - only unique within a location_id no yes no no
location_id string the ID of the location this tag applies to no yes yes no
name string a human-readable name for this tag no yes no yes
name_language_info language_info information regarding the language of name no yes yes no
poi_count integer the number of POIs that have this tag yes yes no no
score float the score of this tag, between 0 and a bit more than 10 yes yes yes no
short_name string a short human-readable name for this tag no yes no no
snippet string a short string describing this tag no yes yes yes
snippet_language_info language_info information regarding the language of snippet no yes yes no
structured_content structured_content structured content related to this tag (no machine translation) no no yes yes
structured_content_language_info language_info information regarding the language of structured_content no no yes no
tour_count integer the number of tours that have this tag yes yes no no
type tag_type the general type of this tag no yes no no

tag_label_with_score

a tag label, along with its score

Name Type Description Orderable? Included by default? May be null? I18n?
count integer number of POIs with this tag label nearby no yes no no
score float score for this tag label no yes no no
tag_label string the tag label to which this score belongs no yes no no

tag_type

the general type of a tag

tag_with_score

a tag, along with its score

Name Type Description Orderable? Included by default? May be null? I18n?
object_score float score for this tag applied to this specific object no yes no no
tag tag the tag to which this score belongs no yes no no

time_range

a time of day range

Name Type Description Orderable? Included by default? May be null? I18n?
end day_time end time of the range, null meaning it ends on a following day no yes yes no
start day_time start time of the range, null meaning it starts on a previous day no yes yes no

time_ranges_by_day

collection of time ranges for all days of the week

Name Type Description Orderable? Included by default? May be null? I18n?
fri time_range[] time ranges for Friday no yes no no
mon time_range[] time ranges for Monday no yes no no
sat time_range[] time ranges for Saturday no yes no no
sun time_range[] time ranges for Sunday no yes no no
thu time_range[] time ranges for Thursday no yes no no
tue time_range[] time ranges for Tuesday no yes no no
wed time_range[] time ranges for Wednesday no yes no no

tour

bookable tours

Name Type Description Orderable? Included by default? May be null? I18n?
attribution attribution[] information about the sources this content came from no yes no no
booking_info booking_info information needed to book this tour no yes no no
content content content about this tour no no yes no
duration float how long the tour lasts (see the duration_unit field for units) no yes yes no
duration_unit duration_unit the unit in which the duration field is expressed. can be "minute", "hour" or "day" no yes yes no
highlights string[] tour highlights, as provided by the tour operator no no yes no
id string the machine-readable identifier of this tour no yes no no
images image[] images related to this tour no yes no no
intro string a short version of the content about this tour no no yes no
location_ids string[] the locations that this tour is related to no no no no
name string a human-readable name of this tour yes yes no no
price price the price of this tour in the currency of the tour operator no yes no no
price_is_per_person boolean if true, it means that the price is the same for each person going on the tour. if false, it usually means that the prices for the second, third, etc. people are discounted in some way no yes no no
properties property[] the properties related to this tour no no no no
score float an indicator of the importance of this tour, generally between 0 and 10 but best suited to relative comparisons and ordering yes yes no no
structured_content structured_content structured content about this tour no no yes no
tag_labels string[] the labels of the tags that apply to this tour no no no no
tags tag_with_score[] the full tags that apply to this tour no no no no
vendor string the vendor offering this tour (deprecated - use booking_info field instead) (viator, withlocals, bemyguest, tiqets, musement) no yes no no
vendor_tour_url string the URL for this tour on the vendor's website (deprecated - use booking_info field instead) no yes no no

translation_provider

a translation provider

vendor_identifier

the identifier for the vendor of a bookable object

way_point

a point (POI or just lat/lng) along a city walk

Name Type Description Orderable? Included by default? May be null? I18n?
coordinates point the geographical location of this way point no yes no no
poi poi corresponding POI for this way point or null if lat/long specified no yes yes no
visit_time integer estimated time to visit this way point no yes no no
walk_to_next_distance integer estimated distance of the walk to the next way point in meters no yes no no
walk_to_next_duration integer estimated duration of the walk to the next way point in minutes no yes no no

Query types

contains_location query whether a set of location IDs contains the given location IDs. may be specified multiple times, in which case the set of location IDs must contain every supplied location ID
contains_tag query the labels of tags. supports "|" for OR and "!" for NOT. for AND, specify the parameter multiple times
exact query by the exact value of the field
exact_negatable query by the exact value of the field, or exclude an exact value by prepending the value with !
none querying this value is not possible
range ">=n", ">n", "<n", "<=n" or "m..n" (inclusive of m, exclusive of n)

Errors

Code Description
1 invalid value for boolean parameter
2 invalid range values
3 invalid order_by
4 unknown fields in exclude_fields
5 field not queryable
6 invalid parameter on endpoint
7 invalid annotation
8 invalid country or state code
9 missing required parameter
10 parameter out of bounds
11 both lat and lng need to be specified
12 given object does not have similarity content
13 invalid value for parameter
14 invalid value for datetime parameter
15 invalid value for persona annotation
16 invalid language
101 object specified by ID does not exist
102 only id is queryable for the source endpoint
201 location_ids is only applicable to tours and articles
202 not enough POIs to plan a walk
301 maximum number of results exceeded (100)
401 missing or invalid authentication information
402 insufficient credit balance to make request
403 account is suspended
404 endpoint not found or invalid version
429 rate limit exceeded
500 internal error
504 query timeout