Using the Reverse Geocoder API
Learn about three API endpoints for reverse geocoding: ReverseGeocodeCountry, ReverseGeocodeAddress, and ReverseGeocodeAddressSuggestions. These endpoints use latitude, longitude, and error radius parameters. ReverseGeocodeCountry retrieves the country na
API Endpoint
The ReverseGeocode endpoint allows you to retrieve the following:
- **Country: **Retrieves the name of a specific country based on the coordinates.
- **Address: **Retrieves the best matching address details, including country, pincode, state, city, and locality based on the coordinates.
- **Address Suggestions: **Retrieves the top 5 matching address suggestions with address details based on the provided coordinates.
The following query parameters are required for all requests:
| Parameter | Data Type | Description | Example |
|---|---|---|---|
type* | string | The reverse geocode type. | Acceptable values: <br />* country |
- address
- address_suggestions |
|
lat* | Float | Latitude value. |17.35386833| |lng* | Float | Longitude value. |82.547853333| |error_radius* | Integer | Error radius in meters. |50|
Reverse Geocode Country
The following example retrieves the name of a specific country based on the coordinates. The following example request returns "India":
:::CodeblockTabs Reverse Geocode Country
GET /reverse-geocode?type=country&lat=74.46097160087743&lng=74.46097160087743&error_radius=123111
:::
{
"status": 200,
"request_id": "rvg | dbb935c1-183c-4538-9b9f-c7744d4cb93d",
"message": "Success",
"data": [
{
"country": "India"
}
],
"error": null
}
Reverse Geocode Address
The ReverseGeocodeAddress endpoint retrieves the best matching address details, including country, pincode, state, city, and locality based on the coordinates.
:::CodeblockTabs Reverse Geocode Address
GET /reverse-geocode?type=address&lat=34.28519821803453&lng=74.46097160087743&error_radius=123111
:::
{
"status": 200,
"request_id": "rvg | d34a5acb-5a01-4cf4-a86d-8b81b6ba25c4",
"message": "Success",
"data": [
{
"level_3": "sopore",
"country": "India",
"pincode": 193201,
"level_4": null,
"level_5": null,
"formatted_address": "sopore, baramulla, jammu and kashmir, 193201",
"address_attributes": null,
"landmark_with_distance": {
"sopore sopore town hall": {
"distance": 19.93,
"landmark_type": "openground"
},
"habibullah eye hospital": {
"distance": 20.84,
"landmark_type": "medical"
},
"boys higher secondary school": {
"distance": 36.24,
"landmark_type": "prefix_match"
},
"bsnl exchange": {
"distance": 81.81,
"landmark_type": "prefix_match"
},
"ssp office": {
"distance": 93.02,
"landmark_type": "corporate"
}
},
"level_1": "jammu and kashmir",
"level_2": "baramulla"
}
],
"error": null
}
Response Details
The response includes the following details in the data array:
| Field | Data Type | Description | Example |
|---|---|---|---|
level_1 | String | The location state name. | jammu and kashmir |
level_2 | String | The location city name. | baramulla |
level_3 | String | The locality or suburb of the city. | sopore |
level_4 | String | The sub-locality of the address when applicable. | |
level_5 | String | Provides more detailed road and street level information. This will be populated in later versions of the API. | |
country | String | Country | India |
pincode | Integer | The pincode of the given address. | 193201 |
formatted_address | String | The formatted address. | sopore, baramulla, jammu and kashmir, 193201 |
address_attributes | String | The specific area associated with the address such as a business, commercial complex, or urban area. This will be populated in later versions of the API. | |
landmark_with_distance | Dictionary of dictionaries | Landmarks, landmark types, and their distances. | See Sample Response |
Reverse Geocode Address Suggestions
NOTE
The ReverseGeocodeAddressSuggestions response includes the same parameters as the ReverseGeocodeAddress response.
The ReverseGeocodeAddressSuggestions endpoint retrieves the top 5 matching address suggestions with address details based on the provided coordinates.
:::CodeblockTabs Reverse Geocode Address Suggestions
GET /reverse-geocode?type=address_suggestions&lat=34.28519821803453&lng=74.46097160087743&error_radius=123111
:::
{
"status": 200,
"request_id": "rvg | f77e1a20-880e-45e4-bead-7176c1071b19",
"message": "Success",
"data": [
{
"level_3": "sopore",
"country": "India",
"pincode": 193201,
"level_4": null,
"level_5": null,
"formatted_address": "sopore, baramulla, jammu and kashmir, 193201",
"address_attributes": null,
"landmark_with_distance": {
"sopore sopore town hall": {
"distance": 19.93,
"landmark_type": "openground"
},
"habibullah eye hospital": {
"distance": 20.84,
"landmark_type": "medical"
},
"boys higher secondary school": {
"distance": 36.24,
"landmark_type": "prefix_match"
},
"bsnl exchange": {
"distance": 81.81,
"landmark_type": "prefix_match"
},
"ssp office": {
"distance": 93.02,
"landmark_type": "corporate"
}
},
"level_1": "jammu and kashmir",
"level_2": "baramulla"
},
{
"level_3": "town hall,sopore",
"country": "India",
"pincode": 193201,
"level_4": null,
"level_5": null,
"formatted_address": "town hall,sopore, baramulla, jammu and kashmir, 193201",
"address_attributes": null,
"landmark_with_distance": {
"sopore sopore town hall": {
"distance": 19.93,
"landmark_type": "openground"
},
"habibullah eye hospital": {
"distance": 20.84,
"landmark_type": "medical"
},
"boys higher secondary school": {
"distance": 36.24,
"landmark_type": "prefix_match"
},
"bsnl exchange": {
"distance": 81.81,
"landmark_type": "prefix_match"
},
"ssp office": {
"distance": 93.02,
"landmark_type": "corporate"
}
},
"level_1": "jammu and kashmir",
"level_2": "baramulla"
},
{
"level_3": "crpf,sopore",
"country": "India",
"pincode": 193201,
"level_4": null,
"level_5": null,
"formatted_address": "crpf,sopore, baramulla, jammu and kashmir, 193201",
"address_attributes": null,
"landmark_with_distance": {
"sopore sopore town hall": {
"distance": 19.93,
"landmark_type": "openground"
},
"habibullah eye hospital": {
"distance": 20.84,
"landmark_type": "medical"
},
"boys higher secondary school": {
"distance": 36.24,
"landmark_type": "prefix_match"
},
"bsnl exchange": {
"distance": 81.81,
"landmark_type": "prefix_match"
},
"ssp office": {
"distance": 93.02,
"landmark_type": "corporate"
}
},
"level_1": "jammu and kashmir",
"level_2": "baramulla"
},
{
"level_3": "iqbal nagar sopore",
"country": "India",
"pincode": 193201,
"level_4": null,
"level_5": null,
"formatted_address": "iqbal nagar sopore, baramulla, jammu and kashmir, 193201",
"address_attributes": null,
"landmark_with_distance": {
"sopore sopore town hall": {
"distance": 19.93,
"landmark_type": "openground"
},
"habibullah eye hospital": {
"distance": 20.84,
"landmark_type": "medical"
},
"boys higher secondary school": {
"distance": 36.24,
"landmark_type": "prefix_match"
},
"bsnl exchange": {
"distance": 81.81,
"landmark_type": "prefix_match"
},
"ssp office": {
"distance": 93.02,
"landmark_type": "corporate"
}
},
"level_1": "jammu and kashmir",
"level_2": "baramulla"
},
{
"level_3": "iqbal market,sopore",
"country": "India",
"pincode": 193201,
"level_4": null,
"level_5": null,
"formatted_address": "iqbal market,sopore, baramulla, jammu and kashmir, 193201",
"address_attributes": null,
"landmark_with_distance": {
"sopore sopore town hall": {
"distance": 19.93,
"landmark_type": "openground"
},
"habibullah eye hospital": {
"distance": 20.84,
"landmark_type": "medical"
},
"boys higher secondary school": {
"distance": 36.24,
"landmark_type": "prefix_match"
},
"bsnl exchange": {
"distance": 81.81,
"landmark_type": "prefix_match"
},
"ssp office": {
"distance": 93.02,
"landmark_type": "corporate"
}
},
"level_1": "jammu and kashmir",
"level_2": "baramulla"
}
],
"error": null
}