ExploreMCPIPPostalCitiesDocsBlog

Distance between two points

Great-circle (haversine) distance between two locations. Pass two city GeoNames ids as `from` and `to`, or raw coordinates as `lat1`, `lng1`, `lat2`, `lng2`. Returns the distance in both kilometres and miles.

GET
/distance

Great-circle (haversine) distance between two locations. Pass two city GeoNames ids as from and to, or raw coordinates as lat1, lng1, lat2, lng2. Returns the distance in both kilometres and miles.

Query Parameters

from?integer

Origin city GeoNames id (use with to).

to?integer

Destination city GeoNames id (use with from).

lat1?number

Origin latitude (use the four raw-coordinate params together).

lng1?number

Origin longitude.

lat2?number

Destination latitude.

lng2?number

Destination longitude.

Response Body

application/json

text/plain

curl -X GET "https://example.com/distance?from=2988507&to=2643743&lat1=48.8534&lng1=2.3488&lat2=51.5085&lng2=-0.1257"
{  "from": {    "geonameId": 2988507,    "name": "Paris",    "asciiName": "Paris",    "countryCode": "FR",    "admin1Code": "string",    "latitude": 48.85341,    "longitude": 2.3488,    "population": 2138551,    "timezone": "Europe/Paris",    "featureCode": "PPLC"  },  "to": {    "geonameId": 2988507,    "name": "Paris",    "asciiName": "Paris",    "countryCode": "FR",    "admin1Code": "string",    "latitude": 48.85341,    "longitude": 2.3488,    "population": 2138551,    "timezone": "Europe/Paris",    "featureCode": "PPLC"  },  "distanceKm": 343.6,  "distanceMiles": 213.5}
Empty
"Country not found"

Search all places GET

Search the full GeoNames gazetteer — ~12M features worldwide (cities, towns, mountains, rivers, regions and more), ordered by population. Filter by name (`q`), `country`, and feature `class`. Also: `GET /places/{geonameId}` for one place and `GET /places/near?lat=&lng=` for the nearest features to a coordinate.

Look up a postal code GET

Resolve a postal/ZIP code to its place name, administrative regions, and coordinates. Covers ~100 countries (GeoNames). Coordinates are approximate and a few countries have reduced precision.