GeoCoding API -v2

API Description

Objective

The GeoCoding API -v2 validates the address of the user by returning a Geolocation.

Input	Output
The address to be verified	The validated address components, formatted address, and geographic coordinates (latitude and longitude). The complete list of output fields is available in the Success Response Details section

API URL

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

API Endpoint

geoCodingV2

Overview

The GeoCoding API -v2 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 API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines 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	Optional	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)

Input

The following table provides the details of the parameters required for the GeoCoding API -v2's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
address	Mandatory	The address to be verified	Not Applicable	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the GeoCoding API -v2:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/geoCodingV2' \
--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 code snippet demonstrates a success response from the GeoCoding API -v2:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "houseNumber": "<House_Number>",
    "street": "<Street>",
    "subSubLocality": "<Sub_Sub_Locality>",
    "subLocality": "<Sub_Locality>",
    "locality": "<Locality>",
    "village": "<Village>",
    "subDistrict": "<Sub_District>",
    "district": "<District>",
    "city": "<City>",
    "state": "<State>",
    "pincode": "<Pincode>",
    "formattedAddress": "<Formatted_Address>",
    "latitude": <Latitude>,
    "longitude": <Longitude>
  },
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the GeoCoding API -v2:

Parameter	Type	Description
status	string	The status of the request
statusCode	number	The HTTP status code representing the result
result	object	The container for the validated address components and geolocation data
houseNumber	string	The house or building number in the address
street	string	The name of the street or road
subSubLocality	string	The smallest subdivision within the locality, such as a colony or area
subLocality	string	The subdivision within the locality, often representing a neighborhood
locality	string	The name of the main locality or town area
village	string	The village name if applicable for rural addresses
subDistrict	string	The sub-district within the district
district	string	The district name of the address
city	string	The city or town name of the address
state	string	The state or union territory name
pincode	string	The postal code or ZIP code
formattedAddress	string	The complete formatted address string
latitude	number	The geographic latitude coordinate of the location
longitude	number	The geographic longitude coordinate of the location
requestId	string	The unique identifier for the request
transactionId	string	The unique identifier for the user journey

Error Responses

The following are some error responses from the API:

Bad Request - Invalid Address

{
  "status": "failure",
  "statusCode": 400,
  "error": "Invalid address.",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Bad Request - Invalid Request

{
  "status": "failure",
  "statusCode": 400,
  "error": "Invalid request.Please try again.",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Unauthorized - Invalid Token

{
  "status": "failure",
  "statusCode": 401,
  "error": "Invalid token.Please try again.",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Unauthorized - Access Denied

{
  "status": "failure",
  "statusCode": 401,
  "error": "Something went wrong.Please try again.",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Unauthorized - Missing/Invalid Credentials

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

Not Found - No Match Found

{
  "status": "failure",
  "statusCode": 404,
  "error": "No match found.",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Internal Server Error

{
  "status": "failure",
  "statusCode": 500,
  "error": "Internal Server Error",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Service Unavailable - External Source Downtime

{
  "status": "failure",
  "statusCode": 503,
  "message": "External source downtime",
  "error": "EXTERNAL_DOWNTIME",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Response Details

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

Status Code	Error	Error Description
400	Invalid address.	The request has an invalid, empty, or unparseable address
400	Invalid request.Please try again.	The request has missing or malformed payload or parameters
401	Invalid token.Please try again.	The request has an expired or invalid authentication token
401	Something went wrong.Please try again.	The request is denied due to insufficient permissions or invalid credentials
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
404	No match found.	The request has an address or record that does not match the provided input
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for investigation
503	External source downtime	The request cannot be processed due to an unavailable external service or data source