geonames.org APIgeonames.org ↗
Access GeoNames geographic data via API: place search, reverse geocoding, postal codes, timezone lookup, and administrative hierarchy for locations worldwide.
curl -X GET 'https://api.parse.bot/scraper/5c4ebe03-64d2-491a-aead-fb7fccb55c42/search_places?name=Paris&limit=5&style=MEDIUM' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for geographic places/toponyms by name, country, feature class, bounding box, or coordinates. Returns paginated results ordered by relevance by default.
| Param | Type | Description |
|---|---|---|
| east | number | Bounding box east longitude |
| lang | string | Language for place names (ISO-639) |
| name | string | Place name to search for |
| west | number | Bounding box west longitude |
| fuzzy | number | Fuzzy matching factor (0-1) |
| limit | integer | Maximum number of results to return |
| north | number | Bounding box north latitude |
| query | string | General search query for place names |
| south | number | Bounding box south latitude |
| style | string | Response verbosity: SHORT, MEDIUM, LONG, FULL |
| offset | integer | Offset for pagination |
| country | string | ISO-3166 country code to filter by |
| orderby | string | Order results by: relevance, population, elevation |
| featureCode | string | GeoNames feature code (e.g. PPLC, ADM1) |
| name_equals | string | Exact place name match |
| featureClass | string | GeoNames feature class: A, H, L, P, R, S, T, U, V |
| continentCode | string | Continent code: AF, AS, EU, NA, OC, SA, AN |
{
"type": "object",
"fields": {
"geonames": "array of place objects with name, lat, lng, countryCode, population, fcode, adminName1",
"totalResultsCount": "integer total matching places"
},
"sample": {
"data": {
"geonames": [
{
"fcl": "P",
"lat": "48.85341",
"lng": "2.3488",
"name": "Paris",
"fcode": "PPLC",
"fclName": "city, village,...",
"countryId": "3017382",
"fcodeName": "capital of a political entity",
"geonameId": 2988507,
"adminCode1": "11",
"adminName1": "Île-de-France",
"population": 2138551,
"adminCodes1": {
"ISO3166_2": "IDF"
},
"countryCode": "FR",
"countryName": "France",
"toponymName": "Paris"
}
],
"totalResultsCount": 1851
},
"status": "success"
}
}About the geonames.org API
The GeoNames API exposes 6 endpoints covering place search, postal code lookup, reverse geocoding, and timezone resolution for geographic locations worldwide. The search_places endpoint returns toponyms filtered by name, bounding box, country, and fuzzy match factor, while timezone resolves any latitude/longitude pair to an IANA timezone ID, GMT/DST offsets, and local sunrise/sunset times.
Place Search and Detail
The search_places endpoint accepts a free-text name or query, optional bounding box coordinates (north, south, east, west), and a fuzzy factor between 0 and 1 to control approximate matching. Results return an array of place objects — each with lat, lng, countryCode, population, fcode (feature code), and adminName1 — plus a totalResultsCount for pagination. For deeper detail on any result, pass its geonameId to get_place_by_id, which returns alternateNames in multiple languages, a bbox boundary object, timezone offsets, and the full administrative hierarchy.
Postal Code Endpoints
postal_code_search accepts postalcode, placename, or their prefix variants (postalcode_startsWith, placename_startsWith), plus an ISO country filter. Each result in the postalCodes array includes the code, placeName, countryCode, lat/lng, and first-level administrative area fields. postal_code_country_info requires no inputs and returns per-country statistics: numPostalCodes, minPostalCode, and maxPostalCode — useful for validating user input ranges before running a search.
Reverse Geocoding and Timezone
reverse_geocode_find_nearby takes a lat/lng pair and optional radius (km) and limit, returning nearby toponyms sorted by distance with their fcode and geonameId. The timezone endpoint accepts the same coordinate inputs and returns timezoneId (IANA format), gmtOffset, dstOffset, rawOffset, and time (current local time string), along with sunrise and sunset timestamps for that location's date.
- Resolve a user-submitted address to coordinates and timezone using
search_placesandtimezonetogether - Validate and normalize postal codes at checkout using
postal_code_searchwith a country filter - Display local time and UTC offset for any map click using the
timezoneendpoint'stimezoneIdandgmtOffsetfields - Find all populated places within a geographic bounding box for regional analytics using
search_placeswithnorth/south/east/westparams - Reverse-geocode device GPS coordinates to the nearest named feature using
reverse_geocode_find_nearby - Audit postal code coverage by country before building a shipping zone matrix using
postal_code_country_info - Fetch alternate-language place names for multilingual UIs via
get_place_by_idwith thealternateNamesarray
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does GeoNames have an official developer API?+
What does `get_place_by_id` return beyond basic coordinates?+
geonameId returns the place's full bounding box (bbox with east/west/north/south), a timezone object with gmtOffset, dstOffset, and timeZoneId, population, and an alternateNames array where each entry has a name and lang field. The style parameter controls verbosity: SHORT omits alternateNames, FULL includes them.Does the API return elevation data for places?+
How should I structure postal code searches for reliable results?+
postal_code_search endpoint works best when you supply at least one of postalcode, placename, postalcode_startsWith, or placename_startsWith together with a country ISO code. Without a country filter, results may span multiple countries and hit the default limit quickly. Use postal_code_country_info first to confirm a country has coverage before querying.Does the API expose administrative boundary polygons or GeoJSON shapes?+
bbox) from get_place_by_id or as a point (lat/lng) across all endpoints. You can fork this API on Parse and revise it to add an endpoint that returns GeoJSON boundaries if your use case requires polygon data.