Reverse Geocoding API

This document outlines the details of the Reverse Geocoding API.

API Description

Objective

The reverse geo-coding 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 API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and ﬁles as form-data 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 API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Valid Values
content-type	Mandatory	This parameter defines the media type for the request payload.	application/json
appId	Mandatory	Application ID shared by HyperVerge	N/A. This is a unique value.
appKey	Mandatory	Application Key shared by HyperVerge	N/A. This is a unique value.
transactionId	Mandatory	Unique ID for the user journey.	N/A. Any defined unique value mapped to a transaction in your business ecosystem.

Inputs

The following table provides information on the parameters used in the request body of the reverseGeoCoding API .

Parameter	Mandatory or Optional	Description
`latitude`	Mandatory	Latitude in the captured location coordinates
`longitude`	Mandatory	Longitude in the captured location coordinates.

Request

The following code shows a standard curl request for the 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 API returns the formatted nearest text address based on google search results of 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

Field	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 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"
       }
   }
}

Status Code	Error Message	Error Description
200	ZERO_RESULTS	The reverse geocoding was successful but returned no results. This may occur if the geocoder was passed a latritude-longitude in a remote location.

Error Response

The following code snippets show the error responses from the API.

Invalid Request

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

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details​

Method - POST​

Headers​

Inputs​

Request​

Success Response​

Success Response Details​

Failure Response​

Error Response​