# US Address Standardization ## Overview {% hint style="warning" %} 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. {% endhint %} 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: ```json { "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** {% tabs %} {% tab title="200" %} ```json [ { "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" } } ] ``` {% endtab %} {% tab title="400" %} ```json { "error": { "status": 400 } } ``` {% endtab %} {% endtabs %} ## 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.