Address Lookup

How It Works

The Address Lookup API allows you to verify and retrieve detailed information about an address. By using this service, you can ensure that the address is valid, complete, and properly formatted. Additionally, you can obtain the geographical coordinates (latitude and longitude) of the address and check for any potential issues such as discrepancies with the user's current location.

Key Features:

• Verifies the validity of an address and provides detailed components (e.g., street number, route, locality, country).
• Returns geolocation data, including latitude and longitude.
• Calculates the distance from the given address to the user’s current location.
• Identifies whether the address is residential, business, or a PO Box.
• Provides insights into address completeness and geocode accuracy.

Integration

Endpoint:

/api/addresslookup

Method:

POST

Base URL:

https://api.boltidentity.com/

Request Headers

{
  "licenseKey": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

Request Body

{
  "address": "109 McNair Rd, Singapore 320109",
  "country": "sg" //provide only ISO 3166-1 country code "Two-letter country code"
}

Example Request (Using Fetch)

const response = await fetch('https://api.yourservice.com/addresslookup', {
    method: 'POST',
    headers: {
        'licenseKey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        address: "109 McNair Road, Singapore 320109",
        country: "sg"
    })
});

const data = await response.json();

Sample Response

{
  "Bolt-Identity": {
    "clientId": "FPC0001",
    "apiService": "addressLookup",
    "requestType": "Paid",
    "report": {
      "referenceID": "fppr-y35cais4jy",
      "jsonResponse": {
        "addressPulse": {
          "status": "Verified",
          "message": "Address is Verified Successfully!",
          "response": {
            "Decision": {
              "inputDetailLevel": "PREMISE",
              "validatedDetailLevel": "PREMISE",
              "geocodeAccuracyLevel": "PREMISE",
              "isAddressComplete": true
            },
            "addressDetails": {
              "formattedAddress": "109 McNair Road, Singapore 320109",
              "postalAddress": {
                "regionCode": "SG",
                "languageCode": "en",
                "postalCode": "320109",
                "addressLines": [
                  "109 McNair Rd"
                ]
              },
              "addressComponents": [
                {
                  "componentName": {
                    "text": "109"
                  },
                  "componentType": "street_number",
                  "confirmationLevel": "CONFIRMED"
                },
                {
                  "componentName": {
                    "text": "McNair Road",
                    "languageCode": "en"
                  },
                  "componentType": "route",
                  "confirmationLevel": "CONFIRMED"
                },
                {
                  "componentName": {
                    "text": "Singapore",
                    "languageCode": "en"
                  },
                  "componentType": "locality",
                  "confirmationLevel": "CONFIRMED"
                },
                {
                  "componentName": {
                    "text": "320109"
                  },
                  "componentType": "postal_code",
                  "confirmationLevel": "CONFIRMED"
                },
                {
                  "componentName": {
                    "text": "Singapore",
                    "languageCode": "en"
                  },
                  "componentType": "country",
                  "confirmationLevel": "CONFIRMED"
                }
              ],
              "geocode": {
                "latitude": 1.3216861,
                "longitude": 103.859158
              }
            },
            "addressType": {
              "business": false,
              "poBox": false,
              "residential": false
            },
            "uspsValidation": false,
            "distance": "4568.683984749039 KM's",
            "current_location": {
              "latitude": 31.4544279,
              "longitude": 74.2788076
            }
          }
        }
      },
      "apiKeyUsed": "api-key-1728234535454-4b4i42ur874",
      "requestDateTime": "2025-01-26T10:42:04.374Z"
    },
    "_id": "6796117cf49dead5638872cb",
    "createdAt": "2025-01-26T10:42:04.376Z",
    "updatedAt": "2025-01-26T10:42:04.376Z",
    "__v": 0
  }
}

Understand Response

Field	Description	Possible Values / Example
status	Indicates the overall status of the address validation request.	Verified, Declined
message	Provides additional information about the request status.	"Address is Verified Successfully!"
Decision.inputDetailLevel	The level of detail provided in the input address.	PREMISE, STREET, LOCALITY
Decision.validatedDetailLevel	The level of detail provided in the validated address.	PREMISE, STREET, LOCALITY
Decision.geocodeAccuracyLevel	The accuracy level of the geocode information.	PREMISE, STREET, LOCALITY
Decision.isAddressComplete	Indicates whether the address is complete and valid.	true, false
addressDetails.formattedAddress	The complete formatted address as a string.	"109 McNair Road, Singapore 320109"
distance	The distance from the provided address to the user’s current location.	"4568.683984749039 KM's"
current_location	The latitude and longitude of the user’s current location.	{ "latitude": 31.4544279, "longitude": 74.2788076 }

Nested Object for postalAddress

Field	Description	Example
regionCode	The country code for the address.	SG
languageCode	The language code for the address.	en
postalCode	The postal code for the address.	320109
addressLines	The address lines for the address.	["109 McNair Rd"]

Nested Array for addressComponents

Field	Description	Example
componentType	The type of address component.	street_number, route, locality
confirmationLevel	Indicates the confirmation status of the component.	CONFIRMED