--- title: Reverse Geocoding API - Convert Coordinates to a Street Address version: 1.0.0 description: Convert a WGS84 latitude/longitude pair into a single human-readable address or place name. Returns the nearest matching location's structured address components (street, city, state, country), a bounding box, and any points of interest, such as a shop or building, at that location. Use the `Accept-Language` header to localize the returned name and address fields to a preferred language, falling back to `en` if the language isn't supported. Both `lat` (-90 to 90) and `lon` (-180 to 180) are required; missing, non-numeric, or out-of-range values return a `400` error. openapi: 3.1.1 servers: - https://api.apifreaks.com/v1.0 paths: 1 operations: 1 schemas: 3 --- ## Table of Contents - [Reverse Geocoding API - Convert Coordinates to a Street Address v1.0.0](#reverse-geocoding-api-convert-coordinates-to-a-street-address-v100) - [Authentication](#authentication) - [Geocoder APIs](#geocoder-apis) - [reverseGeocode](#reversegeocode) - [Parameters](#parameters) - [Responses](#responses) - [Schemas](#schemas) - [ErrorResponse](#errorresponse) - [GeocodeResponse](#geocoderesponse) - [PointOfInterest](#pointofinterest) # Reverse Geocoding API - Convert Coordinates to a Street Address v1.0.0 Convert a WGS84 latitude/longitude pair into a single human-readable address or place name. Returns the nearest matching location's structured address components (street, city, state, country), a bounding box, and any points of interest, such as a shop or building, at that location. Use the `Accept-Language` header to localize the returned name and address fields to a preferred language, falling back to `en` if the language isn't supported. Both `lat` (-90 to 90) and `lon` (-180 to 180) are required; missing, non-numeric, or out-of-range values return a `400` error. Base URLs: * [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0) ## Authentication * API Key (ApiKeyAuthHeader) - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header. * API Key (ApiKeyAuthQuery) - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter. ## Geocoder APIs ### reverseGeocode `GET /geocoder/reverse` *Convert coordinates into a human-readable address* Look up the nearest address or place name for a given latitude and longitude pair. #### Parameters |Name|In|Type|Required|Description| |---|---|---|---|---| |lat|query|number(float)|true|WGS84 latitude value, ranging from -90 to 90.| |lon|query|number(float)|true|WGS84 longitude value, ranging from -180 to 180.| |Accept-Language|header|string|false|Preferred language order for the result name and address, as a comma-separated list of language codes or a single code. Results are returned in the first matched language, falling back to `en` if none match.| > Example responses > Successful geocoding response ```json { "lat": 40.7489669, "lon": -73.985399, "name": "LensCrafters", "category": "shop", "type": "optician", "poi": [ { "name": "LensCrafters", "category": "shop", "type": "optician" }, { "name": "7", "category": "place", "type": "house_number" } ], "street": "West 34th Street", "area": "Manhattan, New York County", "postcode": "10001", "city": "New York", "state_code": "US-NY", "state": "New York", "country_code": "US", "country": "United States", "full_address": "LensCrafters, 7, West 34th Street, Midtown South, Manhattan Community Board 5, Manhattan, New York County, New York, 10001, United States", "bounding_box": [ "40.7489169", "40.7490169", "-73.9854490", "-73.9853490" ] } ``` > Bad Request — Invalid or missing parameters ```json { "error": "Invalid Param Exception", "message": "please pass correct parameters", "path": "/v1.0/geocoder/reverse", "status": 400, "timestamp": "2026-07-22T14:29:45.148Z" } ``` ```json { "error": "Invalid Latitude Provided", "message": "Latitude must be between -90 and 90.", "path": "/v1.0/geocoder/reverse", "status": 400, "timestamp": "2026-07-22T14:29:45.727Z" } ``` ```json { "error": "Invalid Longitude Provided", "message": "Longitude must be between -180 and 180.", "path": "/v1.0/geocoder/reverse", "status": 400, "timestamp": "2026-07-22T14:29:46.267Z" } ``` ```json { "error": "Invalid Parameters Provided", "message": "Please provide valid parameters.", "path": "/v1.0/geocoder/reverse", "status": 400, "timestamp": "2026-07-22T14:29:46.809Z" } ``` #### Responses |Status|Meaning|Description|Schema| |---|---|---|---| |200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful geocoding response|[GeocodeResponse](#geocoderesponse)| |400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Invalid or missing parameters|[ErrorResponse](#errorresponse)| #### Response Headers |Status|Header|Type|Format|Description| |---|---|---|---|---| |200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| |400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| To perform this operation, you must be authenticated by means of one of the following methods: ApiKeyAuthHeader, ApiKeyAuthQuery ## Schemas ### ErrorResponse #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |error|string|false|none|Short error category or exception type.| |message|string|true|none|Human-readable error message describing the failure.| |path|string|false|none|API endpoint path that produced the error.| |status|integer|false|none|HTTP status code returned with the error.| |timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).| ### GeocodeResponse The nearest geocoded location to the given coordinates, with structured address components. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |lat|number(float)|true|none|WGS84 latitude value for the location.| |lon|number(float)|true|none|WGS84 longitude value for the location.| |name|string|false|none|Name for the primary place searched.| |category|string|false|none|High-level category of the place, e.g. amenity, place, natural, building, highway.| |type|string|false|none|Specific kind within the category, e.g. fast_food, city, park, residential, house_number.| |poi|[[PointOfInterest](#pointofinterest)]|false|none|Points of interest at this location.| |street|string|false|none|Street or road name.| |area|string|false|none|Intra-city area below city level, e.g. suburb, borough, quarter, ward, district, sector, zone, tehsil, taluka, neighbourhood.| |postcode|string|false|none|Postal code of the area.| |city|string|false|none|Settlement label appropriate to the country, e.g. city, town, municipality.| |county|string|false|none|Second-tier administrative area, e.g. county, district, shire, prefecture.| |state_code|string|false|none|Subdivision code when available, typically ISO-3166-2 (e.g. US-TX, PK-PB).| |state|string|false|none|First-tier administrative area; varies by country, e.g. state, region, province, division, autonomous community.| |country_code|string|true|none|Two-letter country code in upper case, ISO-3166-1 alpha-2.| |country|string|true|none|Country name of the searched place.| |full_address|string|true|none|Single-line, human-readable address of the location.| |bounding_box|[string]|true|none|Extent of the feature as `[lat_min, lat_max, lon_min, lon_max]` (south, north, west, east) in WGS84 decimal degrees.| ### PointOfInterest A point of interest located at or near a geocoded result. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |name|string|false|none|Name of the point of interest.| |category|string|false|none|High-level category of the point of interest, e.g. amenity, place, natural, building, highway.| |type|string|false|none|Specific kind within the category, e.g. fast_food, city, park, residential, house_number.|