GeoNames vs GeoSearch

GeoSearch serves the GeoNames dataset you already trust — under its CC-BY license, attributed on every page — through the API GeoNames never built, enriched with Natural Earth and geoBoundaries polygons and IP geolocation. The comparison below is about developer experience, not data: response formats, auth, HTTPS, errors and SDKs. GeoNames remains a superb dataset; this page is about how you call it.

Get a free API key

Feature comparison

	GeoNames	GeoSearch
Response format	XML by default; JSON from a separate `…JSON` endpoint path	JSON only, one envelope
Authentication	`username` in the URL query string	`X-API-Key` request header
HTTPS on the free tier	Premium feature (`secure.geonames.org`)	Every tier
Errors	HTTP 200 with the failure inside the body	HTTP status code + `{error:{code,message,details,request_id}}`
Free allowance	10,000 credits/day, 1,000/hour (search 1 credit, nearby place 3)	5,000 requests/month, 2 req/s
Pagination	`maxRows` / `startRow` (offset)	Cursor-based, `next_cursor` / `has_next`
SDKs	Community wrappers	5 official — Go, Python, TypeScript, Ruby, PHP — generated from the OpenAPI spec
Bulk data download	Yes — `allCountries.zip`, refreshed daily, free	—
Paid plans	€40–€500/year depending on credits and uptime SLA	$29 / $99 / $299 per month

Last verified 2026-09-05 against the GeoNames documentation.

When GeoNames is the right choice

You need the data in bulk. GeoNames publishes allCountries.zip — the full worldwide extract, refreshed daily, free to download. GeoSearch has no equivalent.
You are offline or air-gapped. A downloaded GeoNames extract needs no network at all; a hosted API cannot follow you there.
You are on a zero budget or doing academic work. The free web services and the full dumps have carried research projects for two decades at no cost.

When GeoSearch is the better fit

JSON on every endpoint behind one envelope and one X-API-Key header — no XML-to-JSON path split to remember.
HTTPS on every tier, including Free.
Errors arrive on the HTTP status code with a request_id you can quote, not inside a 200 body.
Five SDKs generated from the OpenAPI spec, plus boundary polygons, postal codes, timezones and IP geolocation in the same API.

Migrating from GeoNames

The three most common GeoNames web services, mapped to their GeoSearch equivalents in curl and the published Python SDK.

GeoNames search — curl

# XML by default; JSON is a separate endpoint path
curl "http://api.geonames.org/search\
?q=San+Fran&maxRows=10&username=demo"

# the JSON variant is its own path, not a parameter
curl "http://api.geonames.org/searchJSON\
?q=San+Fran&maxRows=10&username=demo"

GeoSearch — curl, then Python

curl -H "X-API-Key: YOUR_KEY" \
  "https://geosearch.dev/v1/search\
?q=San+Fran&type=city&limit=10"

# pip install git+https://github.com/geosearch-dev/geosearch-python.git
import os
import geosearch

configuration = geosearch.Configuration(
    host="https://geosearch.dev")
configuration.api_key['apiKeyAuth'] = \
    os.environ["GEOSEARCH_API_KEY"]

with geosearch.ApiClient(configuration) as api_client:
    api = geosearch.SearchApi(api_client)
    result = api.search("San Fran",
        type="city", limit=10)

GeoNames get — curl

# XML only; no JSON variant is documented
curl "http://api.geonames.org/get\
?geonameId=5391959&username=demo"

GeoSearch — curl, then Python

curl -H "X-API-Key: YOUR_KEY" \
  "https://geosearch.dev/v1/cities/5391959"

api = geosearch.CitiesApi(api_client)
city = api.get_city(5391959)

GeoNames findNearbyPlaceName — curl

# 3 credits per request; note the lng parameter
curl "http://api.geonames.org/findNearbyPlaceNameJSON\
?lat=37.7749&lng=-122.4194&username=demo"

GeoSearch — curl, then Python

# GeoNames' lng becomes lon here
curl -H "X-API-Key: YOUR_KEY" \
  "https://geosearch.dev/v1/reverse\
?lat=37.7749&lon=-122.4194"

api = geosearch.SearchApi(api_client)
place = api.reverse_geocode(
    37.7749, -122.4194)  # lat, lon

Common questions

Is GeoSearch a drop-in replacement for the GeoNames web services?

No. The endpoints and parameter names differ — GeoSearch was not built to mirror the GeoNames URL scheme. The section above shows how the three most common calls map; the rest follow the same shape: one host, one header, JSON everywhere.

Can I use the data commercially?

Yes. GeoNames data is licensed CC-BY, which allows commercial use with attribution. GeoSearch credits GeoNames on every page, and every source and license is listed on the attribution page.

Do I need a credit card for the free tier?

No. The free tier is 5,000 requests a month with no card and no trial clock — sign up with an email address and you get a key.

Try it on your own queries

The free tier has every endpoint — search your own city, reverse-geocode your own coordinates, and read the response envelope yourself.

Get a free API key Read the docs