Reverse geocode with GeoNames
geonames_reverse_geocodeResolve a latitude/longitude to the country and admin subdivisions that contain it (down to ADM5, each with its geonameId and ISO 3166-2 code where one exists), or the ocean or sea when the point is offshore, plus the nearest populated places with distances; these include neighborhood sections (PPLX) and historical places (PPLH), marked by featureCode. Set featureClasses or featureCodes to list the nearest features of that type instead (peaks, lakes, airports), cities to keep only places above a population tier, and includeTimezone for the IANA timezone with local time, sunrise, and sunset (offshore points get only GeoNames' UTC-offset estimate). A harbor, pier, or shoreline point can fall just outside every country outline and resolve to the sea; coastalBufferKm (up to 50) matches the nearest country within that distance instead. Costs 1 GeoNames credit for containment, with or without the buffer, plus 3 for nearest populated places or 4 for nearest features (nearbyLimit 0 skips them), 1 for the ocean when no country contains the point or lies within the buffer, and 1 for the timezone.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude in decimal degrees, -90 to 90. | |
| lng | Yes | Longitude in decimal degrees, -180 to 180. | |
| cities | No | Keep only nearby populated places with a population of at least 1,000 (cities1000), 5,000 (cities5000), or 15,000 (cities15000), plus seats of admin divisions: GeoNames' cities tiers. Not combinable with featureClasses or featureCodes. | |
| radiusKm | No | Radius in kilometres for the nearby lookup, above 0 and at most 300 (GeoNames' free-tier limit). Default 20. | |
| nearbyLimit | No | How many nearest places or features to list, 0 to 50. Default 5. 0 skips the nearby lookup and its 3 or 4 credits. | |
| featureCodes | No | List the nearest features with these GeoNames codes instead of populated places (MT mountain, PK peak, LK lake, AIRP airport), up to 20, as a list or a comma-separated string. Case-insensitive; a class prefix (T.MT) is dropped. Each code implies its class; with featureClasses too, the two lists intersect, so featureClasses must list exactly these codes' classes. geonames_list_reference topic feature_codes lists every code. Not combinable with cities. | |
| featureClasses | No | List the nearest features of these GeoNames classes instead of populated places: A admin divisions, H water, L areas, P populated places, R roads, S spots and buildings, T terrain, U undersea, V vegetation. A list or a comma-separated string; case-insensitive. With featureCodes too, the two lists intersect: list exactly the classes of those codes, or pass featureCodes alone. Not combinable with cities. | |
| coastalBufferKm | No | When no country contains the point, match the nearest country within this many kilometres, 0 to 50. Default 0: exact containment only. Set it for a harbor, pier, or shoreline point, which can fall just outside a country's outline as GeoNames maps it and otherwise resolves to the sea; a match carries country.distanceInKm. The nearby and timezone lookups keep the exact point. No extra credit. | |
| includeTimezone | No | Also return the timezone: IANA id, UTC offsets, local time, sunrise, and sunset (1 more credit). Default false. | |
| geonamesUsername | No | Your own GeoNames username, so the call spends that account's free credits instead of the server's. Omit it to use the server's account. The account needs free web services enabled on its geonames.org account page. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The nearbyLimit that was applied. | |
| lat | No | The latitude that was looked up. | |
| lng | No | The longitude that was looked up. | |
| error | No | Present when the call failed. Absent on success. | |
| ocean | No | The ocean or sea at the point; present only when no country contains it or lies within coastalBufferKm. | |
| shown | No | Nearby places or features returned. | |
| nearby | No | Nearest places or features, nearest first; empty when nearbyKind is none. | |
| notice | No | Guidance when the point is offshore or unmapped, its country was matched within coastalBufferKm, nothing is nearby, nearby is full, or no IANA timezone covers it. | |
| country | No | The country containing the point, or with coastalBufferKm the nearest country within that distance (then distanceInKm is set); absent offshore and in unmapped areas. | |
| timezone | No | The timezone at the point; present only with includeTimezone. | |
| truncated | No | True when nearby is full at nearbyLimit, so more may lie within the radius. | |
| nearbyKind | No | What nearby lists: populated_places, features (featureClasses or featureCodes was set), or none (nearbyLimit 0). | |
| adminLevels | No | Admin divisions containing the point, first level first; for a country matched within coastalBufferKm, the divisions of its part nearest the point. Empty offshore, and where GeoNames records no subdivision of the country. |