Cities · Data API

Global Cities Directory

A list of the world's cities with their country and state or province.

A reference directory of cities and towns worldwide, each with its country, first-level subdivision (state, province or region) and GeoNames identifier. Developers use it for location autocomplete, address normalisation, and giving AI agents a reliable way to resolve place names to countries.

Get API keyView docs

Source: datasets/world-cities (derived from GeoNames) · CC BY 4.0 · Data from GeoNames (geonames.org) via the datasets/world-cities project, licensed CC BY 4.0

Endpoints

Every request is authenticated with your X-API-Key and counted against your plan.

  • GET /v1/data/global-cities-directory
  • GET /v1/data/global-cities-directory/search?q=...
  • GET /v1/data/global-cities-directory/{key}

Base path /v1/data/global-cities-directory · full reference in the interactive docs. Also exposed as an MCP tool for AI agents.

Fields

FieldTypeDescription
geonameidintGeoNames unique identifier for the city
namestrCity name
countrystrCountry name
subcountrystrState, province or region

What you get

Tens of thousands of cities worldwide
Search by city name
Filter by country and state or province
Stable GeoNames identifiers
Ideal for autocomplete and address validation

FAQ

Does it include coordinates?
No, this directory provides names, country and subdivision; use the GeoNames ID to fetch coordinates elsewhere.
Why do some city names appear more than once?
Many cities share names across countries or regions; the country, subdivision and ID disambiguate them.

Pricing

Simple, transparent pricing

Start free, upgrade when you need more. All plans include full API access.

Free

$0forever

Get started and explore the API

100 requests/day
  • 100 API requests per day
  • All endpoints included
  • Community support
Get Started
Most popular

Pro

$9/month

For production apps and AI agents

10,000 requests/day
  • 10,000 API requests per day
  • All endpoints included
  • Priority support
  • Usage dashboard
Upgrade to Pro

Enterprise

$49/month

Unlimited access for high-volume use

Unlimited requests
  • Unlimited API requests
  • All endpoints included
  • Priority support
  • Usage dashboard
  • Dedicated support channel
Go Enterprise

Getting Started

Start building in minutes

Register for a free API key, make your first request, and upgrade when you're ready.

1

Register

Create an account to get your API key. It's free — no credit card required.

curl -X POST https://api.aristocles.com.au/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "Your Name"}'
2

Make a request

Use your API key in the X-API-Key header to authenticate requests.

curl https://api.aristocles.com.au/v1/data/asx \
  -H "X-API-Key: your_api_key_here"
3

Upgrade

Need more requests? Upgrade to Pro or Enterprise — you'll be redirected to Stripe Checkout.

curl -X POST "https://api.aristocles.com.au/v1/billing/checkout?tier=pro" \
  -H "X-API-Key: your_api_key_here"
4

Check usage

Monitor your daily request count and remaining quota at any time.

curl https://api.aristocles.com.au/v1/usage \
  -H "X-API-Key: your_api_key_here"