Using the Address Validation API

This document guides users on how to utilize the Address Validation endpoint to validate an address. It explains the necessary address details to include in the request body, such as street address, pincode, city, and state. By using this API, users can r

📘 Address Validation V2

This guide covers v2 of the Address Validation API. This version offers improved features and functionality. While v2 is our recommended version, we understand that you might still need access to v1 documentation. You can also contact our support team for further information.

Making a Request

Use the ValidateAddress endpoint to confirm if an address is valid. See the request details below:

Request body:

The request body should contain data object with the following fields:

Parameter	DataType	Description	Example
address*	string	The street address which you want to process.	D1-87 Aravali Heights, Dharuhera Bhiwadi Bypass
city	string	City associated with the provided address.	Dharuhera
state	string	State associated with the provided address.	Haryana
pincode	string	The 6 digit pincode associated with the provided address.	122100
language	string	The language of the address data.	English

Example Request:

{
  "data": {
    "address": "house no 30 boring road patna",
    "city": "patna",
    "state": "bihar",
    "pincode": "800001",
    "language": "English"
  }
}

Understanding the Response

The AddressValidation endpoint will return a JSON response with the validation status of the address along with the address metadata:

Response Schema:

Parameter	Data Type	Description	Example
success	boolean	Indicates if request was successful	true
status_code	integer	HTTP status code for request	200
message	string	Message describing status of request	"Request has been processed"
request_id	string	Unique ID for request	"addval\|jsbvkjs"
address-validity*	string	Validity status of address	"Valid"
address_type*	object	Type of address	{<br />"type": "residential",<br />"sub_type": "society"<br />}
rooftop_confirmed	boolean	Accurately identifies and extracts specific “rooftop” information from the input address, such as door numbers, house numbers, and names of shops, industries, warehouses, or other commercial entities.	true
landmark_confirmed	boolean	If landmark is confirmed	false
is_rural	boolean	If address is rural	false
state_confirmed	boolean	If state is confirmed	true
city_confirmed	boolean	If city is confirmed	true
pin_confirmed	boolean	If PIN is confirmed	true
pin_state_mismatched	boolean	If PIN and state mismatch	false
pin_city_mismatched	boolean	If PIN and city mismatch	false
multi_city_present	boolean	If multiple city tokens detected	false
is_localizable	boolean	The API returns `true`when the address has enough information for the location-finding geocoding models to determine its latitude and longitude with certainty.	true
address_attributes	object	Additional address attributes will be included in future versions of the API
error	string	Error message if any	null

Example Response:

{
    "success": true,
    "status_code": 200,
    "request_id": "addval|5910d468-42a8-420e-a300-88f3a230f87e",
    "message": "Request has been processed",
    "result": {
        "address_validity": "Valid",
        "address_type": {
            "type": "residential",
            "sub_type": "non_identifiable"
        },
        "address_metadata": {
            "rooftop_confirmed": true,
            "is_rural": false,
            "landmark_confirmed": false,
            "state_confirmed": true,
            "city_confirmed": true,
            "pin_confirmed": true,
            "pin_state_mismatched": false,
            "pin_city_mismatched": false,
            "multiple_city_present": false,
            "is_localizable": true
        },
        "address_attributes": {}
    },
    "error": null
}

Error response

{
    "success": false,
    "status_code": 422,
    "request_id": "addval|5c4e1ede-9bf9-42c2-872c-487948326aea",
    "message": "Model Failure Error",
    "result": null,
    "error": {
        "message": "value_error",
        "type": "The Validation Model could not decipher the location and the content of the address. No result predicted for the provided input"
    }
}