Geocoding API

This document outlines the details of the Geocoding API.

API Description

Objective

The Geocoding API converts an address into geographical coordinates (latitude and longitude) and provides detailed information about the location. It internally maps addresses to the most relevant traceable location and retrieves corresponding latitude and longitude coordinates.

Input	Output
The user's address	It returns the following details: Latitude Longitude Address components Formatted address Location Type Viewport

caution

There can be a difference between the expected and actual latitude-longitude coordinates based on the user input.

API Endpoint

geoCoding

API Request Details

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format.

Authentication

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

Method - POST

Headers

Header	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	The media type for the request payload.	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey.	This should be both unique and easily associated with the user's journey in your application(s).

Inputs

The following table provides the details of the fields required for the API's request body:

Parameter	Description	Mandatory or Optional	Allowed Values	Default Values
address	The user's address you want to verify	Mandatory	Not Applicable	Not applicable

Request

The following is a standard cURL request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/geoCoding' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "address": "<Enter_the_address>"
}'

Success Response

The following is a success response from the API:

Success Response

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "addressComponents": [
      {
        "long_name": "<Address_Component_Long_Name>",
        "short_name": "<Address_Component_Short_Name>",
        "types": [
          "<Address_Component_Type_1>",
          "<Address_Component_Type_2>"
        ]
      }
    ],
    "formattedAddress": "<Formatted_Address>",
    "latitude": "<Latitude_Coordinate>",
    "longitude": "<Longitude_Coordinate>",
    "locationType": "<Location_Type>",
    "viewport": {
      "northeast": {
        "lat": "<Northeast_Latitude>",
        "lng": "<Northeast_Longitude>"
      },
      "southwest": {
        "lat": "<Southwest_Latitude>",
        "lng": "<Southwest_Longitude>"
      }
    }
  },
  "metaData": {
    "requestId": "<Request_Identifier>"
  }
}

Success Response Details

Parameter	Type	Description
addressComponents	array	An array containing the separate components applicable to this address. Each component is an object containing information such as long name, short name, and types
formattedAddress	string	A string containing the human-readable address of this location
latitude	number	The latitude coordinates for the location
longitude	number	The longitude coordinates for the location
locationType	string	Stores additional data about the specified location. Possible values include "ROOFTOP", "GEOMETRIC_CENTER", "APPROXIMATE", or "RANGE_INTERPOLATED"
viewport	object	The recommended viewport for displaying the returned result. It is specified as two latitude and longitude values defining the northeast and southwest corners of the viewport. Generally, the viewport is used to frame a result when displaying it to a user.

Failure Response

{
  "status": "failure",
  "statusCode": 400,
  "error": "ZERO_RESULTS",
  "metaData": {
    "requestId": "<Request_Identifier>"
  }
}

Error Response Samples

Invalid Credentials

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

Internal Server Error

{
  "status": "failure",
  "statusCode": 500,
  "message": "internal server error"
}

Failure and Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	ZERO_RESULTS	The API failed to retrieve a location against
400	Missing required request parameters	Some mandatory request parameters are missing in the API request made. Check if "address" is given in request body.
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
403	Access Denied	Please contact the HyperVerge team for resolution
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution