Introduction
Welcome to the RoadGoat Cities API, featuring the world's most comprehensive database about travel destinations - towns, cities, regions, states, countries, and continents. RoadGoat uses advanced machine learning algorithms and synthesizes all the available information to provide the richest and most accurate context about over 4.3+ million destinations - from Indonesian megacities to remote English villages. The RoadGoat Cities API gives access to the same great content that powers RoadGoat, one of the most dynamic travel sites on the web.
Most API developers will want to leverage the Destinations endpoint to power location-based experiences in mobile or web products. From providing basic needs such as a location's photos and coordinates to more abstract context such as "known for" tags, budget ratings, and safety ratings, the RoadGoat API has you covered. For your convenience, we have included language bindings in Shell, Ruby, Python, and JavaScript.
What's the difference between RoadGoat's Cities API and places APIs from Google, Foursquare, Yelp, and Tripadvisor? Learn here.
Getting Started
Obtain Access
If you do not have an existing RoadGoat API account, you will need to create an account in order to sign up as a developer. Once you’ve created your account, make note of your access_key and secret_key since you will need these credentials in order to make a request.
Authorization
RoadGoat's Cities API uses BasicAuth with access_key as username and secret_key as password. As per standard protocol, BasicAuth credentials are sent with Authorization header as Base64 encoded access_key:secret_key.
Output Format
{
"data": {
"id": "6588544",
"type": "destination",
"attributes": {
"slug": "new-york-ny-usa",
"destination_type": "City",
"short_name": "New York",
"name": "New York, NY",
"long_name": "New York, New York State, US",
"population": 8175133,
"latitude": 40.742185,
"longitude": -73.992602
...
},
"relationships": {
...
},
"included": {
...
}
}
}
All outputs follow the JSON:API format put forward by Netflix, unless otherwise mentioned. As an example, see the partial output of the Cities API provided.
Making Your First API Call
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://api.roadgoat.com:80/api/v2/destinations/auto_complete?q=barcelona")
auth_key = Base64.encode64('access_key:secret_key').gsub("\n", " ").strip
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = "Basic #{auth_key}"
response = http.request(request)
puts response.read_body
import http.client
import base64
conn = http.client.HTTPSConnection("api.roadgoat.com:80")
encoded_bytes = base64.b64encode('access_key:secret_key'.encode("utf-8"))
auth_key = str(encoded_bytes, "utf-8")
payload = ''
headers = {
'Authorization': f'Basic {auth_key}'
}
conn.request("GET", "/api/v2/destinations/auto_complete?q=barcelona", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --location \
--request GET 'https://api.roadgoat.com:80/api/v2/destinations/auto_complete?q=barcelona' \
--header "Authorization: Basic $(printf 'access_key:secret_key' | base64)" \
--data-raw ''
// run `npm install follow-redirects` before executing node test.js to ensure the library exists
var net = require('follow-redirects').https;
var fs = require('fs');
var auth_key = Buffer.from('access_key:secret_key').toString('base64');
var options = {
'method': 'GET',
'hostname': 'api.roadgoat.com',
'port': 80,
'path': '/api/v2/destinations/auto_complete?q=barcelona',
'headers': {
'Authorization': `Basic ${auth_key}`
},
'maxRedirects': 20
};
var req = net.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function (chunk) {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
res.on("error", function (error) {
console.error(error);
});
});
req.end();
We recommend testing endpoints using this Postman Collection. If you're unable to do so, you can use the provided code snippets.
Make sure you use BasicAuth as authorization with access_key as username and secret_key as password.
Next Steps
Now that you're all set to use the API, be sure to read these additional links to get you live:
API Endpoints
Rate Limit
Authentication
Attribution
Terms of Use
Platform Policy
License Agreement
API Endpoints
Destinations
This endpoint retrieves details about a Travel Destination.
HTTP Request
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://api.roadgoat.com:80/api/v2/destinations/new-york-ny-usa")
auth_key = Base64.encode64('access_key:secret_key').gsub("\n", " ").strip
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = "Basic #{auth_key}"
response = http.request(request)
puts response.read_body
import http.client
import base64
conn = http.client.HTTPSConnection("api.roadgoat.com:80")
encoded_bytes = base64.b64encode('access_key:secret_key'.encode("utf-8"))
auth_key = str(encoded_bytes, "utf-8")
payload = ''
headers = {
'Authorization': f'Basic {auth_key}'
}
conn.request("GET", "/api/v2/destinations/new-york-ny-usa", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --location \
--request GET 'https://api.roadgoat.com:80/api/v2/destinations/new-york-ny-usa' \
--header "Authorization: Basic $(printf 'access_key:secret_key' | base64)" \
--data-raw ''
// run `npm install follow-redirects` before executing node test.js to ensure the library exists
var net = require('follow-redirects').https;
var fs = require('fs');
var auth_key = Buffer.from('access_key:secret_key').toString('base64');
var options = {
'method': 'GET',
'hostname': 'api.roadgoat.com',
'port': 80,
'path': '/api/v2/destinations/new-york-ny-usa',
'headers': {
'Authorization': `Basic ${auth_key}`
},
'maxRedirects': 20
};
var req = net.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function (chunk) {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
res.on("error", function (error) {
console.error(error);
});
});
req.end();
GET https://api.roadgoat.com/api/v2/destinations/:id
Query Parameters
| Parameter | Description |
|---|---|
| id | ID or slug of a destination. Can be retrieved using Autocomplete endpoint |
Response / Attributes
{
"data": {
"id": "6588544",
"type": "destination",
"attributes": {
"slug": "new-york-ny-usa",
"destination_type": "City",
"short_name": "New York",
"name": "New York, NY",
"long_name": "New York, New York State, US",
"population": 8175133,
"latitude": 40.742185,
"longitude": -73.992602,
"bounding_box": null,
"geonames_id": 5128581,
"walk_score_url": "https://www.walkscore.com/NY/New_York",
"budget": {
"New York, NY": {
"id": 8,
"text": "Extreme"
},
"New York (State)": {
"id": 7,
"text": "Very High"
},
"United States": {
"id": 6,
"text": "High"
}
},
"safety": {
"New York, NY": {
"id": 4,
"text": "High",
"subtext": "Exercise Normal Precaution"
},
"United States": {
"id": 4,
"text": "High",
"subtext": "Exercise Normal Precaution"
}
},
"covid": {
"New York City": {
"metric": 48.574933544965,
"url": "https://covidactnow.org/us/new_york-ny/county/bronx_county",
"text": "Critical"
},
"New York (State)": {
"metric": 42.4086880545932,
"url": "https://covidactnow.org/us/new_york-ny/",
"text": "Critical"
},
"United States": {
"metric": 20.0069563500323,
"url": "https://www.worldometers.info/coronavirus/",
"text": "High"
}
},
"average_rating": 4.55,
"check_in_count": 6762,
"open_elevation_url": "https://api.open-elevation.com/api/v1/lookup?locations=40.742185,-73.992602",
"foursquare_url": "https://api.foursquare.com/v2/venues/search?ll=40.742185,-73.992602&radius=100000",
"kayak_car_rental_url": "https://www.kayak.com/in?a=roadgoatdl&url=/cars/NewYork,NY/NewYork,NY/2021-03-16/2021-03-23/?sort=price_a",
"kayak_lodgings_url": "https://www.kayak.com/in?a=roadgoatdl&url=/hotels/NewYork,NY/2021-03-16/2021-03-23/1adults?sort=userrating_b",
"airbnb_url": "https://www.airbnb.com/s/New York, NY/homes",
"getyourguide_url": "https://getyourguide.com/s/?q=New+York%2C+NY&partner_id=0TQGVTE",
"url": "https://www.roadgoat.com/travel-guides/new-york-ny-usa"
},
"relationships": {
"state": {
"data": {
"id": "2010537",
"type": "destination"
}
},
"country": {
"data": {
"id": "2008781",
"type": "destination"
}
},
"continent": {
"data": {
"id": "10935560",
"type": "destination"
}
},
"known_for": {
"data": [
{
"id": "12",
"type": "known_for"
},
{
"id": "4",
"type": "known_for"
},
{
"id": "3",
"type": "known_for"
},
{
"id": "17",
"type": "known_for"
},
{
"id": "2",
"type": "known_for"
},
{
"id": "8",
"type": "known_for"
},
{
"id": "7",
"type": "known_for"
},
{
"id": "21",
"type": "known_for"
},
{
"id": "9",
"type": "known_for"
},
{
"id": "18",
"type": "known_for"
},
{
"id": "20",
"type": "known_for"
},
{
"id": "6",
"type": "known_for"
}
]
},
"photos": {
"data": [
{
"id": "608",
"type": "photo"
},
{
"id": "585",
"type": "photo"
},
{
"id": "581",
"type": "photo"
},
{
"id": "579",
"type": "photo"
},
{
"id": "578",
"type": "photo"
}
]
},
"mentions": {
"data": [
{
"id": "3",
"type": "mention"
}
]
}
}
},
"included": [
{
"id": "10935560",
"type": "destination",
"attributes": {
"slug": "north-america",
"destination_type": "Continent",
"short_name": "North America",
"name": "North America",
"long_name": "North America",
"latitude": 42.13646,
"longitude": -100.8141,
"bounding_box": {
"sw_lon": -171.486609,
"sw_lat": 8.040134,
"ne_lon": -39.362977,
"ne_lat": 71.088537
},
"average_rating": 4.83333333333333,
"check_in_count": 12877
},
"relationships": {
"known_for": {
"data": []
},
"featured_photo": {
"data": {
"id": "2436",
"type": "photo"
}
}
}
},
{
"id": "2436",
"type": "photo",
"attributes": {
"image": {
"full": "https://cdn.roadgoat.com/uploads/photo/image/2436/landscapes-1426130_1920.jpg",
"large": "https://cdn.roadgoat.com/uploads/photo/image/2436/large_landscapes-1426130_1920.jpg",
"medium": "https://cdn.roadgoat.com/uploads/photo/image/2436/medium_landscapes-1426130_1920.jpg",
"thumb": "https://cdn.roadgoat.com/uploads/photo/image/2436/thumb_landscapes-1426130_1920.jpg",
"avatar": "https://cdn.roadgoat.com/uploads/photo/image/2436/avatar_landscapes-1426130_1920.jpg"
}
}
},
{
"id": "12",
"type": "known_for",
"attributes": {
"slug": "charming",
"name": "Charming",
"icon": "https://cdn.roadgoat.com/images/shared/icons/known-for/charming"
}
},
{
"id": "4",
"type": "known_for",
"attributes": {
"slug": "foodie",
"name": "Foodie",
"icon": "https://cdn.roadgoat.com/images/shared/icons/known-for/foodie"
}
},
{
"id": "3",
"type": "known_for",
"attributes": {
"slug": "nightlife",
"name": "Nightlife",
"icon": "https://cdn.roadgoat.com/images/shared/icons/known-for/nightlife"
}
},
{
"id": "17",
"type": "known_for",
"attributes": {
"slug": "architecture",
"name": "Architecture",
"icon": "https://cdn.roadgoat.com/images/shared/icons/known-for/architecture"
}
},
{
"id": "2",
"type": "known_for",
"attributes": {
"slug": "history",
"name": "History",
"icon": "https://cdn.roadgoat.com/images/shared/icons/known-for/history"
}
},
{
"id": "8",
"type": "known_for",
"attributes": {
"slug": "museums",
"name": "Museums",
"icon": "https://cdn.roadgoat.com/images/shared/icons/known-for/museums"
}
},
{
"id": "7",
"type": "known_for",
"attributes": {
"slug": "performing-arts",
"name": "Performing Arts",
"icon": "https://cdn.roadgoat.com/images/shared/icons/known-for/performing-arts"
}
},
{
"id": "21",
"type": "known_for",
"attributes": {
"slug": "music",
"name": "Music",
"icon": "https://cdn.roadgoat.com/images/shared/icons/known-for/music"
}
},
{
"id": "9",
"type": "known_for",
"attributes": {
"slug": "posh",
"name": "Posh",
"icon": "https://cdn.roadgoat.com/images/shared/icons/known-for/posh"
}
},
{
"id": "18",
"type": "known_for",
"attributes": {
"slug": "lgbt-friendly",
"name": "LGBT Scene",
"icon": "https://cdn.roadgoat.com/images/shared/icons/known-for/lgbt-friendly"
}
},
{
"id": "20",
"type": "known_for",
"attributes": {
"slug": "diversity",
"name": "Diversity",
"icon": "https://cdn.roadgoat.com/images/shared/icons/known-for/diversity"
}
},
{
"id": "6",
"type": "known_for",
"attributes": {
"slug": "shopping",
"name": "Shopping",
"icon": "https://cdn.roadgoat.com/images/shared/icons/known-for/shopping"
}
},
{
"id": "2008781",
"type": "destination",
"attributes": {
"slug": "united-states",
"destination_type": "Country",
"short_name": "United States",
"name": "United States",
"long_name": "United States",
"latitude": 39.76,
"longitude": -98.5,
"bounding_box": {
"sw_lon": -124.733253,
"sw_lat": 24.544245,
"ne_lon": -66.954811,
"ne_lat": 49.388611
},
"average_rating": 4.23076923076923,
"check_in_count": 12498
},
"relationships": {
"known_for": {
"data": []
},
"featured_photo": {
"data": {
"id": "692",
"type": "photo"
}
}
}
},
{
"id": "692",
"type": "photo",
"attributes": {
"image": {
"full": "https://cdn.roadgoat.com/uploads/photo/image/692/travel-guide-of-san-francisco-ca-usa-original.jpg",
"large": "https://cdn.roadgoat.com/uploads/photo/image/692/large_travel-guide-of-san-francisco-ca-usa-original.jpg",
"medium": "https://cdn.roadgoat.com/uploads/photo/image/692/medium_travel-guide-of-san-francisco-ca-usa-original.jpg",
"thumb": "https://cdn.roadgoat.com/uploads/photo/image/692/thumb_travel-guide-of-san-francisco-ca-usa-original.jpg",
"avatar": "https://cdn.roadgoat.com/uploads/photo/image/692/avatar_travel-guide-of-san-francisco-ca-usa-original.jpg"
}
}
},
{
"id": "3",
"type": "mention",
"attributes": {
"title": "52 Places to Go in 2019",
"excerpt": "A starter kit for escaping into the world",
"url": "https://www.roadgoat.com/blog/lists/52-places-to-go-in-2019",
"source_name": "New York Times",
"source_domain": "nytimes.com",
"source_logo": "https://cdn.roadgoat.com/uploads/mention_source/logo/1/avatar_new-york-times-logo.webp"
},
"relationships": {}
},
{
"id": "608",
"type": "photo",
"attributes": {
"image": {
"full": "https://cdn.roadgoat.com/uploads/photo/image/608/travel-guide-of-new-york-ny-usa-original.jpg",
"large": "https://cdn.roadgoat.com/uploads/photo/image/608/large_travel-guide-of-new-york-ny-usa-original.jpg",
"medium": "https://cdn.roadgoat.com/uploads/photo/image/608/medium_travel-guide-of-new-york-ny-usa-original.jpg",
"thumb": "https://cdn.roadgoat.com/uploads/photo/image/608/thumb_travel-guide-of-new-york-ny-usa-original.jpg",
"avatar": "https://cdn.roadgoat.com/uploads/photo/image/608/avatar_travel-guide-of-new-york-ny-usa-original.jpg"
}
}
},
{
"id": "585",
"type": "photo",
"attributes": {
"image": {
"full": "https://cdn.roadgoat.com/uploads/photo/image/585/travel-guide-of-new-york-ny-usa-original.jpg",
"large": "https://cdn.roadgoat.com/uploads/photo/image/585/large_travel-guide-of-new-york-ny-usa-original.jpg",
"medium": "https://cdn.roadgoat.com/uploads/photo/image/585/medium_travel-guide-of-new-york-ny-usa-original.jpg",
"thumb": "https://cdn.roadgoat.com/uploads/photo/image/585/thumb_travel-guide-of-new-york-ny-usa-original.jpg",
"avatar": "https://cdn.roadgoat.com/uploads/photo/image/585/avatar_travel-guide-of-new-york-ny-usa-original.jpg"
}
}
},
{
"id": "581",
"type": "photo",
"attributes": {
"image": {
"full": "https://cdn.roadgoat.com/uploads/photo/image/581/travel-guide-of-new-york-ny-usa-original.jpg",
"large": "https://cdn.roadgoat.com/uploads/photo/image/581/large_travel-guide-of-new-york-ny-usa-original.jpg",
"medium": "https://cdn.roadgoat.com/uploads/photo/image/581/medium_travel-guide-of-new-york-ny-usa-original.jpg",
"thumb": "https://cdn.roadgoat.com/uploads/photo/image/581/thumb_travel-guide-of-new-york-ny-usa-original.jpg",
"avatar": "https://cdn.roadgoat.com/uploads/photo/image/581/avatar_travel-guide-of-new-york-ny-usa-original.jpg"
}
}
},
{
"id": "579",
"type": "photo",
"attributes": {
"image": {
"full": "https://cdn.roadgoat.com/uploads/photo/image/579/travel-guide-of-new-york-ny-usa-original.jpg",
"large": "https://cdn.roadgoat.com/uploads/photo/image/579/large_travel-guide-of-new-york-ny-usa-original.jpg",
"medium": "https://cdn.roadgoat.com/uploads/photo/image/579/medium_travel-guide-of-new-york-ny-usa-original.jpg",
"thumb": "https://cdn.roadgoat.com/uploads/photo/image/579/thumb_travel-guide-of-new-york-ny-usa-original.jpg",
"avatar": "https://cdn.roadgoat.com/uploads/photo/image/579/avatar_travel-guide-of-new-york-ny-usa-original.jpg"
}
}
},
{
"id": "578",
"type": "photo",
"attributes": {
"image": {
"full": "https://cdn.roadgoat.com/uploads/photo/image/578/travel-guide-of-new-york-ny-usa-original.jpg",
"large": "https://cdn.roadgoat.com/uploads/photo/image/578/large_travel-guide-of-new-york-ny-usa-original.jpg",
"medium": "https://cdn.roadgoat.com/uploads/photo/image/578/medium_travel-guide-of-new-york-ny-usa-original.jpg",
"thumb": "https://cdn.roadgoat.com/uploads/photo/image/578/thumb_travel-guide-of-new-york-ny-usa-original.jpg",
"avatar": "https://cdn.roadgoat.com/uploads/photo/image/578/avatar_travel-guide-of-new-york-ny-usa-original.jpg"
}
}
},
{
"id": "2010537",
"type": "destination",
"attributes": {
"slug": "new-york",
"destination_type": "State",
"short_name": "New York (State)",
"name": "New York (State)",
"long_name": "New York (State)",
"latitude": 43.00035,
"longitude": -75.4999,
"bounding_box": {
"sw_lon": -79.7625122070312,
"sw_lat": 40.4773979187012,
"ne_lon": -71.8527069091797,
"ne_lat": 45.0158615112305
},
"average_rating": 4.35714285714286,
"check_in_count": 8548
},
"relationships": {
"known_for": {
"data": []
},
"featured_photo": {
"data": {
"id": "2355",
"type": "photo"
}
}
}
},
{
"id": "2355",
"type": "photo",
"attributes": {
"image": {
"full": "https://cdn.roadgoat.com/uploads/photo/image/2355/34485049333_5a836a9a39_o.jpg",
"large": "https://cdn.roadgoat.com/uploads/photo/image/2355/large_34485049333_5a836a9a39_o.jpg",
"medium": "https://cdn.roadgoat.com/uploads/photo/image/2355/medium_34485049333_5a836a9a39_o.jpg",
"thumb": "https://cdn.roadgoat.com/uploads/photo/image/2355/thumb_34485049333_5a836a9a39_o.jpg",
"avatar": "https://cdn.roadgoat.com/uploads/photo/image/2355/avatar_34485049333_5a836a9a39_o.jpg"
}
}
}
]
}
| Field | Description |
|---|---|
| id | Unique RoadGoat ID |
| slug | Unique RoadGoat slug |
| destination_type | Continent, Country, State, Region, or City |
| short_name | Name excluding parent, such as New York |
| name | Name including parent, such as New York, NY |
| long_name | Name including intermediary parents, such as New York, New York State, US |
| population | Population |
| latitude | Latitude (only for cities) |
| longitude | Longitude (only for cities) |
| bounding_box | Bounding box used for mapping. Excluded for cities |
| geonames_id | Geonames ID |
| walk_score_url | Walk Score url containing Walk Score, Bike Score, and Transit Score |
| budget | Budgetary rating. Based on daily cost of being at the location, including lodging, food, and other. Includes numerical and textual rating. Scale of 1 to 8, with 8 being the most expensive. More info |
| safety | Safety rating. Based on crime and geopolitical risk. Includes numerical and textual rating. Scale of 1 to 5, with 5 being the safest. More info |
| covid | Covid risk, as measured by new daily cases per 100k people. Includes metric value, textual indicator, and url to more complete Covid data pertaining to the destination. More info |
| average_rating | Average rating of the destination provided by RoadGoat users. Scale of 1 to 5, with 5 being the highest. Not all destinations will have a rating |
| check_in_count | Total number of RoadGoat users who have ever checked in to this destination |
| open_elevation_url | The Open Elevation url for retrieving elevation |
| foursquare_url | The Foursquare Places API url for fetching a destination's local venues, such as restaurants, cafes, parks, and museums. You'll need to sign up for the Places API directly with Foursquare, follow their own terms and conditions, and append the url with your API key |
| kayak_car_rental_url | The Kayak url for booking car rentals at the destination. Only provided for cities |
| kayak_lodgings_url | The Kayak url for booking lodging at the destination |
| airbnb_url | The Airbnb url for booking lodging at the destination |
| getyourguide_url | The GetYourGuide url for booking tours near the destination |
Response / Relationships
| Field | Description |
|---|---|
| state | Parent state, such as Florida. Only provided for US cities and towns. Details |
| country | Parent country, such as France. Details |
| continent | Parent continent, such as South America. Details |
| regions | Region(s) that the destination is a part of, such as Long Island or Napa Valley. Details |
| known_for | Tag(s) and icons describing what the destinations is known for, such as Foodie. Details |
| photos | Photo(s) of the destination. Details |
| mentions | Web url(s) of high-quality editorial content such as travel articles and blogs that either mention the destination or feature it. Details |
Autocomplete
This endpoint provides autocomplete results for a query containing a travel destination.
HTTP Request
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://api.roadgoat.com:80/api/v2/destinations/auto_complete?q=barcelona")
auth_key = Base64.encode64('access_key:secret_key').gsub("\n", " ").strip
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = "Basic #{auth_key}"
response = http.request(request)
puts response.read_body
import http.client
import base64
conn = http.client.HTTPSConnection("api.roadgoat.com:80")
encoded_bytes = base64.b64encode('access_key:secret_key'.encode("utf-8"))
auth_key = str(encoded_bytes, "utf-8")
payload = ''
headers = {
'Authorization': f'Basic {auth_key}'
}
conn.request("GET", "/api/v2/destinations/auto_complete?q=barcelona", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --location \
--request GET 'https://api.roadgoat.com:80/api/v2/destinations/auto_complete?q=barcelona' \
--header "Authorization: Basic $(printf 'access_key:secret_key' | base64)" \
--data-raw ''
// run `npm install follow-redirects` before executing node test.js to ensure the library exists
var net = require('follow-redirects').https;
var fs = require('fs');
var auth_key = Buffer.from('access_key:secret_key').toString('base64');
var options = {
'method': 'GET',
'hostname': 'api.roadgoat.com',
'port': 80,
'path': '/api/v2/destinations/auto_complete?q=barcelona',
'headers': {
'Authorization': `Basic ${auth_key}`
},
'maxRedirects': 20
};
var req = net.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function (chunk) {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
res.on("error", function (error) {
console.error(error);
});
});
req.end();
GET https://api.roadgoat.com/api/v2/destinations/auto_complete?q=barcelona
Query Parameters
| Parameter | Description |
|---|---|
| q | A string containing the name of the travel destination, such as Charleston, SC or Zaragoza, Spain. |
Response / Attributes
| Field | Description |
|---|---|
| id | Unique RoadGoat ID |
| slug | Unique RoadGoat slug |
| destination_type | Continent, Country, State, Region, or City |
| short_name | Name excluding parent, such as New York |
| name | Name including parent, such as New York, NY |
| long_name | Name including intermediary parents, such as New York, New York State, US |
| latitude | Latitude (only for cities) |
| longitude | Longitude (only for cities) |
| bounding_box | Bounding box used for mapping. Excluded for cities |
| average_rating | Average rating of the destination provided by RoadGoat users. Scale of 1 to 5, with 5 being the highest. Not all destinations will have a rating |
| check_in_count | Total number of RoadGoat users who have ever checked in to this destination |
Response / Relationships
| Field | Description |
|---|---|
| known_for | Tag(s) and icons describing what the destinations is known for, such as Foodie. Details |
| featured_photo | Featured photo of the destination. Details |
Special Topics
Budget
RoadGoat's proprietary Budget ratings are built using advanced data science techniques. Budget ratings represent the daily cost of being at the location, including lodging, food, and other expenses (such as car service and public transportation). Ratings represent an average across a destination's seasonality.
Budget ratings are derived by analyzing more than 15 open data sets such as historical hotel and vacation home prices and consumer price indices (e.g. US CPI).
| Rating | Text | Example Places |
|---|---|---|
| 8 | Extreme | New York. Zermatt. |
| 7 | Very High | Tokyo. Paris. |
| 6 | High | Barcelona. Rome. |
| 5 | Medium High | Singapore. Montreal. |
| 4 | Medium | Rio de Janeiro. Singapore. |
| 3 | Medium Low | Quito. Cairo. |
| 2 | Low | Delhi. Sofia. |
| 1 | Very Low | Phnom Penh. La Paz. |
Safety
RoadGoat's proprietary Safety ratings are built using advanced data science techniques. They reflect the crime and geopolitical risk of a given destination. Ratings are derived by analyzing more than 15 open data sets such as the US State Department's travel advisories and local crime data. Includes numerical and textual rating, as illustrated below:
| Rating | Text | Subtext | Example Places |
|---|---|---|---|
| 5 | Very High | Exercise Normal Precaution | Switzerland, Singapore |
| 4 | High | Exercise Normal Precaution | Costa Rica, United Kingdom |
| 3 | Medium | Exercise Increased Caution | Peru, Angola |
| 2 | Low | Reconsider Travel | El Salvador, Chad |
| 1 | Very Low | Travel Not Advised | Iraq, Venezuela |
Covid
Covid risk, as measured by daily new cases per 100k population. Country data is provided by . State and county level data (US destinations only) is provided by CovidActNow. Response includes value, textual indicator (as illustrated below), and urls to further Covid data for the destination. For a more comprehensive API about US Covid scores, we recommend CovidActNow's API.
| Range | Text |
|---|---|
| ≤75 | Extreme |
| ≤25 | Critical |
| ≤10 | High |
| ≤1 | Medium |
| <1 | Low |
Parents, Children, and Regions
id is provided for parent state, country, and/or continent. Note that state is only provided for US cities and towns.
Additionally, id is provided for regions, such as Long Island, Napa Valley, or Basque Country, that a city is part of. Note that Regions do not have parents.
Known For
Returns characteristic(s) for which the destinations is known for. Includes id, slug, name, and icon.Can include one one or more of the following:
| name | icon color |
icon svg |
|
|---|---|---|---|
| Charming |  |
 |
|
| Foodie |  |
 |
|
| Nightlife |  |
 |
|
| Architecture |  |
 |
|
| History |  |
 |
|
| Museums |  |
 |
|
| Performing Arts |  |
 |
|
| Music |  |
 |
|
| Hipster |  |
 |
|
| Hippie |  |
 |
|
| Posh |  |
 |
|
| Family Friendly |  |
 |
|
| LGBT Friendly |  |
 |
|
| Diversity |  |
 |
|
| Beach Town |  |
 |
|
| College Town |  |
 |
|
| Ski Town |  |
 |
|
| Outdoorsy |  |
 |
|
| Wineries |  |
 |
|
| Shopping |  |
 |
| Format | Color | Sources | url |
|---|---|---|---|
| SVG | Single | Font Awesome, Game Icons, Typicons, and Material Design Icons | Add .svg to end of url |
| PNG (48x48) | Multi | Icons8 | Add -48.png to end of url |
| PNG (96x96) | Multi | Icons8 | Add -96.png to end of url |
Photos
The Destinations endpoint will provide photos while all other references to a destination will provide featured_photo. photos includes up to 5 photo(s) of the destination whereas featured_photo includes only one photo of the destination. Photos are either open source high quality images individually selected by RoadGoat's travel experts, or proprietary images provided by RoadGoat users. Each photo object includes id and urls for a photo in the following sizes:
| name | max width | max height |
|---|---|---|
| full | no max | no max |
| large | 1080 | 720 |
| medium | 322 | 161 |
| thumb | 200 | 200 |
| avatar | 56 | 56 |
Mentions
Mentions are web url(s) of high-quality editorial content that either mention the destination or feature it. Editorial content is hand-selected by RoadGoat travel experts to only include the highest quality articles. Fields include title, excerpt, url, source_name (such as New York Times), source_domain (such as nytimes.com), and source_logo.
Comparing Location APIs
What's the difference between RoadGoat's Cities API and places APIs from Google, Foursquare, Yelp, and Tripadvisor?
RoadGoat's API describes destinations - neighborhoods, towns, cities, regions, states, countries, and continents. In contrast, other location APIs give context about venues such as cafes, restaurants, hotels, and parks. The two types of location-based APIs work complementary side by side with each other to give context about both destinations and venues.
Rate Limit
Usage of the API is subject to an hourly rate limit of 1,000 API calls per hour. If you are currently over limits, our API will return a 429 error.
Usage Guidelines
API Terms of Use
In order for us to continue to serve the tech industry, we ask that you help us maintain our platform and follow our rules, including our Platform Policy, Data License Agreement, and Privacy Policy.
Data Retention
We understand that caching RoadGoat may increase the speed of your application; however, we ask that you abide by the following rules around retaining RoadGoat data:
- You may cache the RoadGoat ID or slug for up to 1 month.
- All other RoadGoat data may be kept for a maximum of 24 hours without being refreshed. The data of users who haven’t authenticated your app may only be stored for up to three hours.
Attribution
You must credit RoadGoat when using our Cities API product. You must both link back to the corresponding destination page and give visual attribution.
Linking to Us
Give your users the opportunity to learn more about the places they see in your app. To do this, provide links back to corresponding RoadGoat destination's travel guide pages whenever you display any data retrieved from our API. A destination's RoadGoat url is provided by the url field in the Destinations endpoint. Common approaches include:
- Linking the place name directly
- Creating your own place page and linking that back to us
- Having some other dedicated “More Details” link
The url is a standard mobile-friendly web link. Make sure to supply the ref parameter whose value is your app's CLIENT_ID so that we can confirm your app is attributing properly. Don't set rel="nofollow" on your links back to RoadGoat.
Use the sample link below as a reference for how to format your URLs: https://www.roadgoat.com/travel-guides/new-york-ny-usa/34apsdk23048aslg?ref=CLIENT_ID
Visual Attribution
You can attribute RoadGoat by downloading our attribution images and hosting on your CDN.
Contact Support
You can contact support here.
Errors
The Cities API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 403 | Forbidden -- The goat requested is hidden for administrators only. |
| 404 | Not Found -- The specified goat could not be found. |
| 405 | Method Not Allowed -- You tried to access a goat with an invalid method. |
| 406 | Not Acceptable -- You requested a format that isn't json. |
| 410 | Gone -- The goat requested has been removed from our servers. |
| 418 | I'm a teapot. |
| 429 | Too Many Requests -- You're requesting too many goats! Slow down! |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |