canonical: https://jentic.com/apis/roadgoat.com/roadgoat-cities

# RoadGoat Cities API

The RoadGoat Cities API returns travel content for cities and destinations worldwide in JSON:API format. A keyword search or auto-complete call finds a destination, and the detail call returns its descriptions, latitude and longitude, population, budget and safety scores, walk_score and bike_score, known_for tags, average rating, photos, and nearby destinations. Related photos and destinations arrive as sideloaded resources in the included array.

## For AI agents

Find a city with RoadGoat search or auto-complete, then read its budget, safety, known-for tags, walk and bike scores, photos, and nearby destinations.

## Scope

Does not book flights or hotels, give turn-by-turn directions, or list individual venues. Use for city and destination travel content only.

## Capabilities

- Search destinations by city name or country with the q parameter
- Auto-complete partial destination names for a travel search box
- Read a destination's budget value and safety score with their text labels
- Return known_for tags with scores, such as food or nightlife, for a city
- Get walk_score, bike_score, population, and coordinates for a destination
- Load related photos and nearby_destinations from the JSON:API included array

## Use cases

### AI trip-planning assistant

A travel agent built on an LLM needs facts about a city rather than its own recollection. Through Jentic it searches for 'city travel info', calls RoadGoat's GET /destinations with q set to the city, then GET `/destinations/{id}` for the match, with HTTP Basic credentials added by the developer's own instance. It answers with the city's budget text, safety text, and top known_for tags.

Example prompt: Call GET /destinations with q 'Lisbon', take the first result's id, call GET `/destinations/{id}`, and report budget.text, safety.text, and the three highest-scoring known_for tags

### Destination comparison for travellers

A traveller choosing between cities wants a side-by-side view. GET `/destinations/{id}` returns budget and safety objects with numeric values and text labels, along with walk_score, bike_score, average_rating, and reviews_count, so an app can rank candidate cities on cost, safety, and getting around on foot or by bike.

Example prompt: Call GET `/destinations/{id}` for three destination ids and rank them by safety.value, then by budget.value

### Search box auto-complete

Travel booking forms need fast suggestions while a user types. GET `/destinations/auto_complete` takes a partial q string and returns matching destinations, and the chosen id can be passed straight to GET `/destinations/{id}` for the full record.

Example prompt: Call GET `/destinations/auto_complete` with q 'San Fr' and return the destination names and ids

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/destinations` | Search destinations by keyword |
| GET | `/destinations/auto_complete` | Auto-complete destination names |
| GET | `/destinations/{id}` | Get a destination's full record |

## Key resources

- **Destinations** — Cities with descriptions, coordinates, population, budget, safety, known_for tags, walk and bike scores, and ratings
- **Included resources** — Sideloaded photos and nearby destinations returned in the JSON:API included array

## Why Jentic

- **Setup:** Wiring RoadGoat by hand means encoding the API key and secret as an HTTP Basic header and parsing JSON:API responses where photos and nearby destinations sit in a separate included array. Through Jentic you install once, import RoadGoat Cities from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** RoadGoat exposes three read operations, and the destination id sits in the URL path (`/destinations/{id}`), so a rule can bound your agent to search only, auto-complete only, or detail lookups. You choose which of these operations it may call.
- **Credential handling:** Your RoadGoat key and secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find a city' or 'get destination safety score', and Jentic returns the matching RoadGoat operation with its input schema so the agent passes q or id correctly.

## Related APIs

- **OpenTripMap** — Tourist attractions and points of interest near a location
- **Amadeus Safe Place** — Neighbourhood safety ratings for travellers
- **Foursquare** — Venue and place search within a destination
- **OpenWeatherMap** — Current weather and forecasts by coordinates

## FAQ

### What authentication does the RoadGoat Cities API use?

Per its OpenAPI spec, the RoadGoat Cities API uses HTTP Basic authentication, with your RoadGoat API key as the username and your secret as the password. Through Jentic both values are held by your own instance and combined into the Basic header at call time, so the agent never sees them.

### What data does a RoadGoat destination record include?

GET `/destinations/{id}` returns name, slug, short_description, description, long_description, latitude, longitude, population, budget, safety, known_for, walk_score, bike_score, average_rating, reviews_count, wikipedia_url, and website. Relationships point to photos and nearby_destinations, which are sideloaded in the included array.

### What are the rate limits for the RoadGoat Cities API?

The OpenAPI spec documents a 429 rate-limit response on destination search but does not state a numeric limit. Check https://www.roadgoat.com/business/cities-api for the current limits on your plan.

### Is there a RoadGoat MCP server?

You do not need an MCP server to give your agent RoadGoat. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls the search, auto-complete, and destination detail operations when it needs them.

### How do I look up a city through Jentic?

Search Jentic for 'get travel info for a city', load the searchDestinations operation (GET /destinations), and pass the city name as q. Then call getDestination with the returned id for the full record. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the RoadGoat Cities API?

Yes, though all three operations are reads. A rule that allows only GET `/destinations/auto_complete` keeps a search-box helper from pulling full destination records, and adding GET `/destinations/{id}` widens it to detail lookups. Every call the agent makes is logged.
