Address Match API

This document outlines the details of the Address Match API.

API Description

Objective

The Address Match API compares two input addresses and returns an overall similarity score. It also provides segment-level comparison scores for individual address components such as house, street, locality, city, state, and pincode, enabling a detailed evaluation of address similarity.

Input	Output
The two addresses for comparison	Overall similarity score along with individual scores for each address component

API URL

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

API Endpoint

address_match

Overview

The Address Match API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files 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 Address Match 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.	multipart/form-data
`appId`	Mandatory	The application ID shared by HyperVerge	Not Applicable - this is a unique value
`appKey`	Mandatory	The application key shared by HyperVerge	Not Applicable - this is a unique value
`transactionId`	Mandatory	The unique ID for the customer journey	Not Applicable - this is a unique value related to a transaction in your application

Input

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

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
`address1`	Mandatory	string	The first address. This value will be compared with the `address2` parameter	A valid address string	Not Applicable
`address2`	Mandatory	string	The second address. This value will be compared with the `address1` parameter	A valid address string	Not Applicable
`returnMatchingSegments`	Optional	string	Indicates if the response should return the matching address segments	`yes` or `no`	Not Applicable
`region`	Optional	string	The region for comparison logic, e.g., "ind" for India	Not Applicable	Not Applicable
`returnSegmentScores`	Optional	string	Indicates if the response should return segment-level scores	`yes` or `no`	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Address Match API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/address_match' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'address1="<Enter_the_first_address>"' \
--form 'address2="<Enter_the_second_address>"' \
--form 'returnMatchingSegments="<Enter_yes_or_no>"' \
--form 'region="<Enter_the_region>"' \
--form 'returnSegmentScores="<Enter_yes_or_no>"'

Success Response

The following code snippet demonstrates the success response from the Address Match API when the parameters returnSegmentScores and returnMatchingSegments are enabled in the request:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "overall_score": 0.5,
        "segments": {
            "house": {
                "match": "no",
                "score": 0
            },
            "street_name_or_landmark_nearby": {
                "match": "no",
                "score": 0.55
            },
            "locality": {
                "match": "no",
                "score": 0.35
            },
            "city": {
                "match": "yes",
                "score": 1
            },
            "state": {
                "match": "yes",
                "score": 1
            },
            "pincode": {
                "match": "no",
                "score": 0
            }
        }
    }
}

The following success responses are returned when the parameters returnSegmentScores and returnMatchingSegments are not enabled in the request:

returnSegmentScores not enabled
returnMatchingSegments not enabled

When the returnSegmentScores parameter is not included, only the match results (without scores) for each segment are returned:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "overall_score": 0.51,
        "segments": {
            "house": {
                "match": "no"
            },
            "street_name_or_landmark_nearby": {
                "match": "no"
            },
            "locality": {
                "match": "no"
            },
            "city": {
                "match": "yes"
            },
            "state": {
                "match": "yes"
            },
            "pincode": {
                "match": "no"
            }
        }
    }
}

When the returnMatchingSegments parameter is set to "no" or not included, the response only returns the overall similarity score without any segment-level information:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "overall_score": 0.5
    }
}

Success Response Details

The following table outlines the details of the success response from the Address Match API:

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code for the request
result	object	The result object containing the address match details
overall_score	float	The overall score representing the similarity between the two addresses, ranging from 0 to 1
segments	object	An object containing segment-level match results
house	object	The matching result and score (if applicable) for the house number or building
house.match	string	Indicates if the house information matches between the two addresses
house.score	float	The similarity score for the house segment, ranging from 0 to 1
street_name_or_landmark_nearby	object	The matching result and score (if applicable) for the street name or nearby landmark
street_name_or_landmark_nearby.match	string	Indicates if the street or landmark matches between the two addresses
street_name_or_landmark_nearby.score	float	The similarity score for the street or landmark segment (if returned)
locality	object	The matching result and score (if applicable) for the locality or area
locality.match	string	Indicates if the locality matches between the two addresses
locality.score	float	The similarity score for the locality segment (if returned)
city	object	The matching result and score (if applicable) for the city
city.match	string	Indicates if the city matches between the two addresses
city.score	float	The similarity score for the city segment (if returned)
state	object	The matching result and score (if applicable) for the state
state.match	string	Indicates if the state matches between the two addresses
state.score	float	The similarity score for the state segment (if returned)
pincode	object	The matching result and score (if applicable) for the pincode
pincode.match	string	Indicates if the pincode matches between the two addresses
pincode.score	float	The similarity score for the pincode segment (if returned)

Error Responses

The following are some error responses from the Address Match API:

Invalid Request Parameters
Missing/Invalid Credentials
Internal Server Error

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

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

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

Error Response Details

A failure or error response from the Address Match API 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 `address1`	The address input fields in the request are either missing or invalid	Ensure both `address1` and `address2` are provided 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 is an internal server error. Kindly contact the HyperVerge Team for investigation and support.	Contact the HyperVerge team for resolution

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details​

Method - POST​

Headers​

Input​

Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​