US Address Standardization

Overview

Our other endpoints ex: Mailing, automatically standardize your address data upon ingestion, utilizing the US Address Standardization API is a separately provided service if you want to standardize and retain the cleaned data internally.

One other key difference to note the Address Standardization API also leverages address.* instead of api.* for all the API calls.

The US Address Standardization API allows you to standardize single or multiple addresses. It provides two main endpoints for address standardization.

Endpoints

1. Standardize a Single Address

• URL: address.heypoplar.com/v1/standardize

• Method: GET

• Description: Standardizes a single address.

• Query Parameters: Address details (see Input Format section)

2. Standardize Multiple Addresses

• URL: address.heypoplar.com/v1/standardize

• Method: POST

• Description: Standardizes multiple addresses in a single request.

• Request Body: JSON array of address objects (see Input Format section)

Input Format

You can provide address information in one of the following formats:

1. Full address string

2. Address line 1 + City/State/ZIP

3. Address line 1 + ZIP Code

4. Address line 1 + City + State

Input Fields

Field	Type	Description
full_address	string	Full input address, used as an alternative to providing individual address components.
address_line1	string	First line of the street address (e.g., house number and street name).
address_line2	string	Second line of the street address (e.g., apartment or suite number). Optional in all combinations.
city	string	City name. When used without state and zip_code, this should contain the entire last line of the address (City, State ZIP Code).
state	string	State abbreviation (e.g., "CA" for California).
zip_code	string	ZIP Code (5-digit or ZIP+4).

Important Note on the 'city' Field

When using the "Address line 1 + City/State/ZIP" format, the city field should contain the entire last line of the address, including the city name, state, and ZIP code. For example:

{
  "address_line1": "123 Main St",
  "city": "San Francisco, CA 94105"
}

This format allows for more flexible input, especially when the full address is available but not parsed into separate components.

Response Examples

200

[
    {
        "query_index": 0,
        "address_line1": "123 MAIN ST",
        "city": "SAN FRANCISCO",
        "state": "CA",
        "zip_code": "94105",
        "address_components": {
            "del_point": "233",
            "post_office_city": "SAN FRANCISCO",
            "primary_name": "MAIN",
            "primary_num": "123",
            "suffix": "ST",
            "zip_addon": "1804"
        },
        "usps_analysis": {
            "ame_footnotes": "N#V#",
            "dpv_cmra": "N",
            "dpv_footnotes": "AABB",
            "dpv_no_stat": "Y",
            "dpv_return_code": "Y",
            "dpv_vacant": "N"
        },
        "metadata": {
            "carrier_rte": "C010",
            "cong_district": "11",
            "county_name": "SAN FRANCISCO",
            "county_num": "075",
            "elot_code": "D",
            "elot_num": "0270",
            "latitude": 37.79157,
            "longitude": -122.3946,
            "precision": "Street",
            "rdi": "Residential",
            "record_type": "S",
            "zip_class_code": "Standard"
        }
    }
]

400

{
    "error": {
        "status": 400
    }
}

Output Format

The API returns a JSON array of standardized address results. Each result includes standardized address components, USPS analysis information, and additional metadata.

Output Fields

Main Result Fields

Field	Type	Description
query_index	integer	Index of the query for batch processing.
address_line1	string	Standardized first line of the street address.
address_line2	string	Standardized second line of the street address (e.g., apartment or suite).
city	string	Standardized city name.
state	string	Standardized state abbreviation.
zip_code	string	Standardized ZIP Code (5-digit or ZIP+4).

Address Components

Field	Type	Description
del_point	string	Delivery point code (last 2 digits of the ZIP+4).
pmb_des	string	Private Mailbox (PMB) designator.
pmb_num	string	Private Mailbox (PMB) number.
post_dir	string	Post-directional suffix (e.g., "NW" for northwest).
post_office_city	string	City name of the Post Office.
pre_dir	string	Pre-directional prefix (e.g., "N" for north).
primary_name	string	Primary street name.
primary_num	string	Primary number (house or building number).
secndry_num	string	Secondary address number (e.g., apartment number).
secndry_num2	string	Second secondary number if applicable.
suffix	string	Street suffix (e.g., "St", "Ave").
unit_des	string	Unit designator (e.g., "Apt" for apartment).
unit_des2	string	Second unit designator if applicable.
zip_addon	string	ZIP+4 add-on code (last 4 digits of the ZIP Code).

USPS Analysis

Field	Type	Description
ame_footnotes	string	Address Matching Engine footnotes indicating specific address issues.
dpv_cmra	string	DPV® footnote indicating whether the address is a Commercial Mail Receiving Agency (CMRA).
dpv_footnotes	string	DPV® footnotes, providing information on address validation results.
dpv_no_stat	string	Indicates if the address is a "No-Stat" (an address that does not receive mail).
dpv_return_code	string	Standard DPV® return code showing validation results.
dpv_vacant	string	Indicates if the address is marked as vacant.
llk_ind	string	LACSLink® indicator, showing if the address has been converted.
llk_return_code	string	LACSLink® return code providing more details on the address conversion.
slk_footnotes	string	SuiteLink footnotes showing additional address processing details.

Metadata

Field	Type	Description
carrier_rte	string	Carrier route code used by USPS for delivery.
cong_district	string	Congressional district for the address.
county_name	string	Name of the county for the address.
county_num	string	County number.
default_flag	string	Indicates if the address is a default record.
elot_code	string	Enhanced Line-of-Travel (eLOT®) code.
elot_num	string	eLOT® number.
latitude	number	Latitude of the address.
longitude	number	Longitude of the address.
precision	string	Precision of the geocoding.
rdi	string	Residential Delivery Indicator, indicating if the address is residential or commercial.
record_type	string	Type of address record (e.g., Firm, PO Box, Street).
zip_class_code	string	ZIP classification code indicating the type of ZIP (e.g., Unique, PO Box only).

Error Responses

The API may return the following error responses:

• 400: Bad Request

• 413: Payload Too Large

• 422: Unprocessable Entity

• 500: Internal Server Error

• 503: Service Unavailable

Each error response includes an error message in the response body.

Usage Notes

• For batch processing, use the POST method to standardize multiple addresses efficiently.

• The API provides detailed USPS® analysis, including DPV® and LACSLink® results.

• Geocoding information is included when available.