Reverse Geocoding API

This document outlines the details of the Reverse Geocoding API.

API Description

Objective

The Reverse Geocoding API converts a latitude-longitude coordinate pair into a human-readable address.

Input	Output
The user's location coordinates	The user's equivalent human-readable address

API URL

https://ind-engine.thomas.hyperverge.co/v1/reverseGeoCoding

API Endpoint

reverseGeoCoding

Overview

The Reverse Geocoding API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should send all data in JSON format through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the Reverse Geocoding API.

API Request Details

Method - POST

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload.	application/json
appId	Mandatory	Application ID shared by HyperVerge	Not Applicable - this is a unique value
appKey	Mandatory	Application Key shared by HyperVerge	Not Applicable - this is a unique value
transactionId	Mandatory	Unique ID for the user journey	Not Applicable - any defined unique value mapped to a transaction in your business ecosystem

Input

The following table provides the details of the parameters required for the Reverse Geocoding API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
latitude	Mandatory	number	Latitude in the captured location coordinates	A valid decimal coordinate value	Not Applicable
longitude	Mandatory	number	Longitude in the captured location coordinates	A valid decimal coordinate value	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Reverse Geocoding API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/reverseGeoCoding' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "latitude": <Enter_the_latitude_coordinates>,
    "longitude": <Enter_the_longitude_coordinates>
}'

Success Response

The following is a response for a valid request where the Reverse Geocoding API returns the formatted nearest text address based on the coordinates:

{
  "status": "success",
  "statusCode": "200",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "result": {
    "details": {
      "plus_code": {
        "compound_code": "<Plus_Code_Compound_Code>",
        "global_code": "<Plus_Code_Global_Code>"
      },
      "results": [
        {
          "address_components": [
            {
              "long_name": "<Address_Component_Long_Name>",
              "short_name": "<Address_Component_Short_Name>",
              "types": [
                "<Address_Component_Type>"
              ]
            }
          ],
          "formatted_address": "<Formatted_Address>",
          "geometry": {
            "location": {
              "lat": "<Latitude_Coordinate>",
              "lng": "<Longitude_Coordinate>"
            },
            "location_type": "<Location_Type>",
            "viewport": {
              "northeast": {
                "lat": "<Northeast_Latitude>",
                "lng": "<Northeast_Longitude>"
              },
              "southwest": {
                "lat": "<Southwest_Latitude>",
                "lng": "<Southwest_Longitude>"
              }
            }
          },
          "place_id": "<Place_ID>",
          "plus_code": {
            "compound_code": "<Plus_Code_Compound_Code>",
            "global_code": "<Plus_Code_Global_Code>"
          },
          "types": [
            "<Place_Type>"
          ]
        }
      ],
      "status": "<Status>"
    }
  }
}

Success Response Details

The following table outlines the details of the success response from the Reverse Geocoding API:

Parameter	Type	Description
result.details.plus_code	object	Contains the plus code information for the location
result.details.results	array	Array of address results for the given coordinates
result.details.results[].address_components	array	Array of address components for each result
result.details.results[].formatted_address	string	The complete formatted address
result.details.results[].geometry	object	Contains location and viewport information
result.details.results[].place_id	string	Unique identifier for the place
result.details.results[].types	array	Array of place types

Failure Response

The following code snippet shows a response from the Reverse Geocoding API where it returns a success status but with zero results:

{
   "status": "success",
   "statusCode": "200",
   "metaData": {
       "requestId": "<Request_ID>",
       "transactionId": "<Transaction_ID>"
   },
   "result": {
       "details": {
           "results": [],
           "status": "ZERO_RESULTS"
       }
   }
}

Error Responses

The following code snippets show the error responses from the Reverse Geocoding API:

Invalid Request

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message. The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
200	ZERO_RESULTS	The reverse geocoding was successful but returned no results. This may occur if the geocoder was passed a latitude-longitude in a remote location.	Verify that the provided coordinates are valid and within a geocodable region
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey in the request headers. Check the dashboard's credentials tab