# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.heypoplar.com/api/endpoints/us-address-standardization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.