I Built a Global Location Data API with 12M+ Cities — Here's How

Every developer has hit this wall. You're building an app. You need a city search dropdown, or postal code validation, or timezone detection. Simple stuff. You look at Google Maps Platform pricing. You close the tab. That's why I built LocalityAPI.

The Problem With Existing Solutions

Google Maps Platform is comprehensive but expensive. $5 per 1,000 Place Autocomplete requests. $17 per 1,000 Geocoding requests. For a startup doing 100,000 requests per month that's $500-1,700 monthly just for location data. Before you've made a dollar.

Free alternatives exist but come with serious tradeoffs. GeoNames has the data but the API is unreliable and the documentation is from 2009. IP geolocation APIs give you approximate city from IP but can't search by name. Most 'free geocoding APIs' are wrappers around OpenStreetMap Nominatim with strict rate limits and no SLA.

Self-hosting is possible but means downloading and maintaining 100GB+ of planet data, setting up PostGIS, writing your own API layer, and hoping nothing breaks on a Sunday night. There had to be a better way.

What I Built

LocalityAPI is a REST API giving developers access to:

• 12M+ global places — cities, towns, villages, suburbs, hamlets across 248 countries

• 1.8M+ postal codes — covering 60+ countries with coordinates and admin regions

• IANA timezones — for every location

• Administrative hierarchy — countries → states/provinces → counties → cities

• Confidence scores — each record is cross-validated across multiple authoritative sources

Seven clean endpoints. One API key. Under 20ms response time.

The Technical Stack

Database: PostgreSQL 16 with PostGIS. The places table has 13.5 million records with spatial indexes for radius searches and full-text search indexes for city name queries.

Data pipeline: We import from multiple sources and cross-validate. Each record gets a confidence score from 1-3 depending on how many independent sources agree on the data. This is something no competitor does.

API layer: FastAPI with async PostgreSQL connections via asyncpg. Redis for caching frequent queries. Nginx as reverse proxy.

Response times in production:

Endpoint Response Time

/v1/search 50-150ms

/v1/autocomplete 10-20ms

/v1/postal 80-120ms

/v1/nearby 80-120ms

/v1/countries 5ms

The API Design Philosophy

Single header authentication. Pass X-API-Key: your_key on every request. No OAuth dance, no token refresh, no SDK required.

Consistent response shape. Every endpoint returns results, count and query_ms. You always know where your data is.

Honest about data quality. The confidence field (1-3) tells you how reliable a record is. Most APIs hide this. We surface it.

No forced pagination. For most use cases you want the top 10 results immediately. Add limit=50 if you need more.

Code Examples

Search a city (JavaScript):

const response = await fetch(

'https://api.localityapi.com/v1/search?q=Dubai&country=AE',

{ headers: { 'X-API-Key': 'your_key_here' } }

);

const data = await response.json();

// data.results[0].name → 'Dubai'

// data.results[0].timezone → 'Asia/Dubai'

// data.query_ms → 8

Postal code to coordinates (Python):

import requests

def postal_to_coords(code, country):

response = requests.get(

'https://api.localityapi.com/v1/postal',

params={'code': code, 'country': country},

headers={'X-API-Key': 'your_key_here'}

)

data = response.json()

return data['lat'], data['lng']

lat → 51.501, lng → -0.1247

Real Use Cases

• Address forms. Use /v1/countries for the country dropdown, /v1/admin for states/provinces, /v1/autocomplete for the city field. Three API calls, fully dynamic address form, no hardcoded lists to maintain.

• Timezone detection. User signs up and enters their city. One call to /v1/search returns their IANA timezone. All their notifications go out at the right local time.

• Shipping validation. E-commerce checkout enters postal code. One call to /v1/postal validates it exists and returns city and coordinates. Catch invalid postal codes before the order ships.

• Location-based filtering. User grants location permission, you get lat/lng, one call to /v1/nearby returns all cities within 50km. Filter your database by those cities.

Pricing

Free tier: 1,000 calls/day. No credit card required. Sign up and get a key in 30 seconds.

Paid plans start at $19/month for 50,000 calls/day. Compare that to Google's $500-1,700 for the same volume.

What's Coming

• Points of interest (restaurants, hotels, hospitals, landmarks)

• Reverse geocoding (lat/lng to full address)

• Street-level address search

• Administrative boundary polygons

Try It

Free tier at localityapi.com — no credit card, key in 30 seconds.

Full documentation at docs.localityapi.com

Questions? I read every email at [email protected]

_If you found this useful, a like or share helps others find it. And if you build something with LocalityAPI, I'd love to hear about it in the comments.

_