NAV
shell ruby python javascript

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"
                    }
                ]
            },
            "travelers": {
                "data": [
                    {
                        "id": "1716",
                        "type": "user"
                    },
                    {
                        "id": "532",
                        "type": "user"
                    },
                    {
                        "id": "573",
                        "type": "user"
                    },
                    {
                        "id": "1243",
                        "type": "user"
                    },
                    {
                        "id": "1959",
                        "type": "user"
                    }
                ]
            },
            "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"
                }
            }
        },
        {
            "id": "1716",
            "type": "user",
            "attributes": {
                "name": "Joe Avino",
                "url": "https://www.roadgoat.com/travelers/joe-avino",
                "avatar_url": "https://cdn.roadgoat.com/uploads/user/avatar/1716/avatar_unnamed.jpg"
            }
        },
        {
            "id": "532",
            "type": "user",
            "attributes": {
                "name": "Peter Gerard",
                "url": "https://www.roadgoat.com/travelers/peter-gerard",
                "avatar_url": "https://cdn.roadgoat.com/uploads/user/avatar/532/avatar_profilepic.jpeg"
            }
        },
        {
            "id": "573",
            "type": "user",
            "attributes": {
                "name": "Michael Marranzini",
                "url": "https://www.roadgoat.com/travelers/michael-marranzini",
                "avatar_url": null
            }
        },
        {
            "id": "1243",
            "type": "user",
            "attributes": {
                "name": "Michael Williams",
                "url": "https://www.roadgoat.com/travelers/michael-williams",
                "avatar_url": null
            }
        },
        {
            "id": "1959",
            "type": "user",
            "attributes": {
                "name": "Peter St.Wecker",
                "url": "https://www.roadgoat.com/travelers/peter-st-wecker",
                "avatar_url": "https://cdn.roadgoat.com/uploads/user/avatar/1959/avatar_profilepic.jpeg"
            }
        }
    ]
}
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
travelers Up to 5 RoadGoat users that have been to the location. Ideal for adding social verification. 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.Travel destinations must be a country, region, US state, city, or town

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:

Icon will provide a url such as https://www.roadgoat.com/images/shared/icons/shopping to fetch one of three icons:

name icon
color
icon
svg
Charming Charming Charming
Foodie Foodie Foodie
Nightlife Nightlife Nightlife
Architecture Architecture Architecture
History History History
Museums Museums Museums
Performing Arts Performing Arts Performing Arts
Music Music Music
Hipster Hipster Hipster
Hippie Hippie Hippie
Posh Posh Posh
Family Friendly Family Friendly Family Friendly
LGBT Friendly LGBT Friendly LGBT Friendly
Diversity Diversity Diversity
Beach Town Beach Town Beach Town
College Town College Town College Town
Ski Town Ski Town Ski Town
Outdoorsy Outdoorsy Outdoorsy
Wineries Wineries Wineries
Shopping Shopping 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

Travelers

Up to 5 RoadGoat travelers that have been to the destination. Only RoadGoat users who set visibility to public will be provided. Fields include id, name, url, and avatar_url. avatar_url is a 56x56 profile picture of the user. RoadGoat B2B customers use travelers to add social validation to destinations on their sites and apps.

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:

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:

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.