The Address Normalization API provided by Chimney allows you to verify and normalize addresses according to USPS conventions. By making a POST request to the /address/normalize endpoint of the api.chimney.io API, you can ensure that the addresses conform to standard formats.

Endpoint

The endpoint for accessing the Address Normalization API is:

POST https://api.chimney.io/address/normalize

Request Body

The API request should include the following in the request body:

  • Content-Type: application/json

The requests field is an array of address objects, where each object represents an address to be normalized.

{
  "requests": [
    {
      "street": "2800 N 24th St",
      "city": "Phoenix",
      "state": "Arizona",
      "zip": "85008",
      "requestId": ""
    }
  ]
}

Each address object should contain the following fields:

  • street (string, required): Street address including the house number, street name, and street type.
  • city (string, required): Address city.
  • state (string, required): Address state. Can be two-letter abbreviation (AZ) or full name (Arizona).
  • zip (string, required): US ZIP code or ZIP+4 code.
  • requestId (string or null): Optional parameter to uniquely identify the requested address and its response.

Responses

The API provides various response codes and formats based on the success or failure of the request.

Successful Response (200)

The successful response contains the following structure:

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "results": {
    "addresses": [
      {
        "oldHashes": [],
        "street": "2800 N 24th St",
        "city": "Phoenix",
        "cityAlias": null,
        "state": "AZ",
        "zip": "85008",
        "county": "Maricopa",
        "hash": "90a01b18e3834e349a8d1d07d7e086ba",
        "latitude": 33.47865,
        "longitude": -112.03029,
        "geoLocation": [
          33.47865,
          -112.03029
        ],
        "requestId": 0,
        "formattedStreet": "N 24th St",
        "streetNoUnit": "2800 N 24th St",
        "meta": {
          "error": false,
          "normalized": true,
          "hashed": true
        },
        "houseNumber": "2800",
        "zipPlus4": "1049",
        "vacant": "No",
        "countyFipsCode": "04013",
        "carrierRoute": "C009",
        "congressionalDistrict": "07",
        "timeZone": "Mountain",
        "utcOffset": -7,
        "daylightSavingsTime": false,
        "dpvMatchCode": "D",
        "dpvFootnotes": "AAN1",
        "footnotes": "B#H#"
      }
    ],
    "meta": {
      "apiVersion": "2.0",
      "results": {
        "requestCount": 1,


        "normalizedCount": 1,
        "notNormalizedCount": 0,
        "hashedCount": 1,
        "notHashedCount": 0,
        "errorCount": 0
      },
      "performance": {
        "totalRequestTime": 278,
        "startTime": "2021-10-06T20:28:23.617Z",
        "endTime": "2021-10-06T20:28:23.895Z"
      },
      "requestId": "M2CiaQam0XxT64K"
    }
  }
}

Error Responses

The API may return error responses with appropriate status codes (400, 401, 403, 404, 405, 429, 500) along with an error message. The response will be in JSON format.

Example Usage

Here's an example of how to make a POST request to the Address Normalization API endpoint:

curl --request POST \
  --url https://api.chimney.io/address/normalize \
  --header 'Accept: application/json, application/xml' \
  --header 'Authorization: [Your API Token]' \
  --header 'Content-Type: application/json' \
  --data '{
    "requests": [
      {
        "street": "2800 N 24th St",
        "city": "Phoenix",
        "state": "Arizona",
        "zip": "85008",
        "requestId": ""
      }
    ]
  }'

Replace [Your API Token] with your actual Chimney API token.

Conclusion

The Address Normalization API provided by Chimney allows you to verify and normalize addresses according to USPS conventions. By making a POST request to the /address/normalize endpoint of the api.chimney.io API and providing the necessary information, you can receive address normalization results in a structured JSON format. Each requested address is considered a billable API request.