canonical: https://jentic.com/apis/mashape.com/geodb-cities

# Mashape GeoDB Cities API

GeoDB Cities API is a curated geographic database covering countries, regions, administrative divisions, populated places, and time zones, distributed via the RapidAPI marketplace under the wft-geo-db host. Each city record carries population, latitude/longitude, elevation, and Wikidata IDs, with nearby-city and distance-radius search built in. The API is intended for autocomplete UIs, store-locator features, and AI agents that need to look up places without licensing a full GIS dataset. Authentication uses a RapidAPI key passed as the `X-RapidAPI-Key` header.

## For AI agents

Search cities, countries, regions, and administrative divisions with population, coordinates, and nearby-place lookups for autocomplete and store-locator use cases.

## Scope

Does not handle full-address geocoding, routing, or map tile rendering - use for city, country, and administrative-division lookups only.

## Capabilities

- Search cities filtered by name prefix, country, minimum population, and radius
- Look up details for a specific city including population and coordinates
- List countries and the administrative divisions within each
- Find nearby cities or administrative divisions within a distance from a point
- Retrieve the local time and timezone for a given city
- Convert between place IDs and Wikidata IDs

## Use cases

### City Autocomplete in Sign-up Forms

Web and mobile sign-up flows often need a city autocomplete that returns the right city the moment the user starts typing. GeoDB Cities supports prefix search with country and minimum-population filters so you can show only the cities relevant to your audience and avoid surfacing tiny villages. A typical autocomplete fires after 3 characters and returns the top 5 matches.

Example prompt: Call `GET `/geo/cities`?namePrefix=San&minPopulation=100000&limit=5` and render the returned city names in the dropdown.

### Store Locator Nearby Search

Retailers powering 'stores near me' features need to map a user's city to nearby populated places to determine which store catchment to query. GeoDB exposes nearby-cities and radius search around a coordinate so the locator can resolve the user's input city to a list of neighbouring cities with population thresholds.

Example prompt: Call `GET `/geo/locations/{locationId}/nearbyCities`?radius=50&limit=20` and feed the returned city IDs into the store catchment query.

### Travel App City Browser

Travel and itinerary apps let users browse cities by country and admin region. GeoDB's hierarchical endpoints (countries > admin divisions > cities) return the structured navigation tree, with each city carrying population, elevation, and a Wikidata ID for cross-linking to other data sources like images or articles.

Example prompt: Call `GET `/geo/countries/{countryCode}/regions/{regionCode}/cities`` to render the city list under a chosen region.

### AI Agent Location Resolution

An AI travel or logistics agent often needs to resolve a freeform city mention to a canonical place ID with coordinates. Jentic exposes GeoDB's prefix and radius search behind intent-based discovery, and stores the RapidAPI key in the vault so the agent never embeds it in prompts.

Example prompt: Search Jentic for 'find city by name', load the GeoDB `/geo/cities` schema, and execute it with namePrefix='Lyon' to resolve the canonical city record.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/geo/cities` | Search cities with prefix, country, and population filters |
| GET | `/geo/cities/{cityId}` | Fetch a specific city's details |
| GET | `/geo/cities/{cityId}/dateTime` | Get local date and time for a city |
| GET | `/geo/countries` | List countries |
| GET | `/geo/countries/{countryId}` | Fetch a specific country |
| GET | `/geo/adminDivisions` | Search administrative divisions |
| GET | `/geo/adminDivisions/{divisionId}/nearbyCities` | Cities near an administrative division |

## Key resources

- **Cities** — Search and look up populated places with population, coordinates, and timezone.
- **Countries** — List countries and look up their metadata.
- **Admin Divisions** — Hierarchical regions, states, and provinces under each country.
- **Nearby Search** — Find cities or divisions within a radius of a coordinate.
- **Locale** — Look up local time and timezone for a city.

## Why Jentic

- **Setup:** Wiring the GeoDB Cities API by hand means registering on RapidAPI, sending the X-RapidAPI-Key header on every call, and pointing at the wft-geo-db.p.rapidapi.com host. Through Jentic you install once, import the GeoDB Cities API from the API Directory, store the RapidAPI key once, and your agent calls it.
- **Permission scoping:** GeoDB puts the resource id in the URL path (`/geo/cities/{cityId}`, `/geo/countries/{countryId}`), so a rule can pin your agent to one city or country and its nearby lookups. You choose the operations it may call, and since this surface is read-only, it fetches place data without any write access unless you add it.
- **Credential handling:** Your RapidAPI key is stored once, encrypted, by your own Jentic One instance and injected into the request header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find a city by name' or 'list nearby cities', and Jentic returns the matching GeoDB operation with its query schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Geocodio API** — Geocodio focuses on US/Canada address geocoding with rich enrichment fields.
- **LocationIQ API** — LocationIQ provides global forward and reverse geocoding plus map tiles.
- **PositionStack API** — PositionStack is a forward and reverse geocoding API with global coverage.
- **GeoNames API** — GeoNames is a free geographic database with extensive feature codes and translations.

## FAQ

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

GeoDB Cities is distributed via RapidAPI and authenticates with the `X-RapidAPI-Key` header tied to your RapidAPI account subscription. Through Jentic, the key is stored encrypted in your Jentic One instance and injected at execution time.

### Can I search cities by minimum population with the GeoDB Cities API?

Yes. `GET `/geo/cities`` accepts `minPopulation` and `maxPopulation` query parameters along with `namePrefix` and `countryIds`, so you can return, for example, only cities above 500,000 people that match a prefix.

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

Rate limits depend on the RapidAPI plan tier you subscribe to. The free tier is typically 1 request per second with a daily quota, while paid plans raise both the per-second and monthly quotas. RapidAPI returns standard quota headers on each response.

### Can I find cities near a specific coordinate with the GeoDB Cities API?

Yes. Use `GET `/geo/locations/{locationId}/nearbyCities`` or the location-coordinate variants to find populated places within a configurable radius, with optional minimum-population and country filters.

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

Run `pip install jentic`, then use Jentic's search with the query 'find city by name'. Jentic loads the `/geo/cities` operation schema and your agent executes it with the chosen `namePrefix` and population filter - the RapidAPI key is applied automatically.

### Does the GeoDB Cities API include Wikidata IDs?

Yes. Each city, region, and country record includes a `wikiDataId` field, letting you cross-reference GeoDB results with Wikidata-linked datasets such as images, descriptions, or related entities.

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

Yes. Because you self-host Jentic One, your own rules decide which GeoDB operations and credentials the agent may use, so you can allow only the city and country lookups it needs, such as GET `/geo/cities` and GET `/geo/countries.` Since GeoDB puts the resource id in the URL path (for example `/geo/cities/{cityId}` or `/geo/countries/{countryId}`), you can pin the agent to a single city or country and its nearby lookups. The whole surface is read-only, so the agent fetches place data without any write access.