Geolocation Validation API

This document outlines the details of the Geolocation Validation API.

API Description

Objective

The Geolocation Validation API verifies if the distance between a customer's address in textual format and their location coordinates captured in an application is within the configured range of distance.

Input	Output
The customer's address and location coordinates.	The boolean result of the distance verification between the two inputs and the details of the distance.

API URL

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

API Endpoint

geoLocationValidation

Overview

The Geolocation Validation 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 Geolocation Validation 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 customer 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 Geolocation Validation 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
address	Mandatory	string	Address of the user in text format	A valid address string	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Geolocation Validation API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/geoLocationValidation' \
--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>,
    "address": "<Enter_the_valid_address>"
}'

Success Response

The following is a response for a valid request made to the Geolocation Validation API:

{
  "statusCode": "200",
  "distance": 8539795.18642073,
  "locationMatch": false,
  "addressInformation": {
    "results": [
      {
        "address_components": [...]
      }
    ]
  }
}

Success Response Details

The following table provides the details of the fields in a success response from the Geolocation Validation API:

Parameter	Type	Description
distance	number	The field returns the distance between the address and location coordinates in metres.
locationMatch	boolean	By default, this field returns a "true" value if the distance is less than 1000m. The field value is configurable based on your requirement.
address_components	array	The field provides additional information on the entered address.
types	array	The types[] array indicates the type of the returned result. This array contains a set of zero or more tags identifying the type of feature returned in the result. For example, a geocode of "Chicago" returns "locality" which indicates that "Chicago" is a city, and also returns "political" which indicates it is a political entity. Components might have an empty types array when there are no known types for that address component.
formatted_address	string	This is a string containing the human-readable address of this location.
postcode_localities[]	array	It is an array denoting all the localities contained in a postal code. This is only present when the result is a postal code that contains multiple localities.
geometry	object	This field contains the following information: location contains the geocoded latitude, longitude value. For normal address lookups, this field is typically the most important. location_type stores additional data about the specified location. The following values are currently supported: ROOFTOP indicates that the returned result is a precise geocode for which we have location information accurate down to street address precision. RANGE_INTERPOLATED indicates that the returned result reflects an approximation (usually on a road) interpolated between two precise points (such as intersections). Interpolated results are generally returned when rooftop geocodes are unavailable for a street address. GEOMETRIC_CENTER indicates that the returned result is the geometric center of a result such as a polyline (for example, a street) or polygon (region). APPROXIMATE indicates that the returned result is approximate. viewport contains the recommended viewport for displaying the returned result, specified as two latitude,longitude values defining the southwest and northeast corner of the viewport bounding box. Generally the viewport is used to frame a result when displaying it to a user. bounds (optionally returned) stores the bounding box which can fully contain the returned result. Note that these bounds may not match the recommended viewport.
partial_match	boolean	The geocoder did not return an exact match for the original request, though it was able to match part of the requested address. You may wish to examine the original request for misspellings and/or an incomplete address.

Failure Response

The following code snippet shows a failure response from the Geolocation Validation API:

{
  "statusCode": "200",
  "distance": null,
  "locationMatch": false,
  "addressInformation": {
    "results": [],
    "status": "ZERO_RESULTS"
  }
}

Error Responses

The following code snippets show the error responses from the Geolocation Validation API:

Credentials Error

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

Server Error

{
  "message": "Internal Server Error",
  "statusCode": 500,
  "status": "failure"
}

Latitude Error

{
"message": "Input Validation Error: requires property \"latitude\"",
"statusCode": 400,
"status": "failure"
}

Longitude Error

{
"message": "Input Validation Error: requires property \"longitude\"",
"statusCode": 400,
"status": "failure"
}

Address Error

{
"message": "Input Validation Error: requires property \"address\"",
"statusCode": 400,
"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
400	Input Validation Error: requires property "latitude"	The latitude parameter is missing from the request	Include a valid numeric latitude value in the request body
400	Input Validation Error: requires property "longitude"	The longitude parameter is missing from the request	Include a valid numeric longitude value in the request body
400	Input Validation Error: requires property "address"	The address parameter is missing from the request	Include a valid address string in the request body
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
500	Internal Server Error	There was an error with HyperVerge's server	Contact the HyperVerge team for resolution
-	OVER_DAILY_LIMIT	It indicates any one of the following: the API key is missing or invalid; billing has not been enabled on your account; a self-imposed usage cap has been exceeded; or the provided method of payment is no longer valid	Check your billing settings or contact the HyperVerge team for resolution
-	OVER_QUERY_LIMIT	You are over your quota	Contact the HyperVerge team to review your quota
-	REQUEST_DENIED	The request was denied	Contact the HyperVerge team for resolution
-	INVALID_REQUEST	It generally indicates one of the following scenarios: the query (address, components or latlng) is missing; or the API received an invalid result_type or location_type	Ensure all required query parameters are present and valid
-	UNKNOWN_ERROR	The request could not be processed due to a server error. It may succeed if you try again	Retry the request. If the issue persists, contact the HyperVerge team