# USPS

> Check U.S. addresses with the Postal Service: standardize an address and get its ZIP+4, whether it is deliverable, a business or vacant, look up the city and state for a ZIP Code, and find the ZIP Code for an address.

App · 3 actions. Web page: https://docs.lodol.com/docs/integrations/usps

## Actions

### Get city and state for a ZIP Code

Get the city and state USPS has for a 5-digit ZIP Code.

**Inputs**

- ZIP Code (`zip_code`, text, required): The 5-digit ZIP Code, such as 50314.

**Outputs**

- `ZIPCode` (text): The ZIP Code looked up
- `city` (text): City
- `found` (true/false): Whether USPS matched the address
- `message` (text): USPS's reason when it found no match, else empty
- `state` (text): Two-letter state code

**Example output**

```json
{
  "ZIPCode": "50314",
  "city": "DES MOINES",
  "found": true,
  "message": null,
  "state": "IA"
}
```

### Get ZIP Code for an address

Get the ZIP Code and ZIP+4 of a street address in a city and state. An address USPS can't match comes back with found set to false and the reason.

**Inputs**

- Street address (`street_address`, text, required): The building number and street, such as 1600 Pennsylvania Ave NW.
- Apartment or suite (`secondary_address`, text): The apartment, suite or unit, such as Apt 2B. It can also go at the end of the street address.
- City (`city`, text, required): The city.
- State (`state`, text, required): The state. One of: `AL` (Alabama (AL)), `AK` (Alaska (AK)), `AS` (American Samoa (AS)), `AZ` (Arizona (AZ)), `AR` (Arkansas (AR)), `AA` (Armed Forces Americas (AA)), `AE` (Armed Forces Europe, Middle East, Africa and Canada (AE)), `AP` (Armed Forces Pacific (AP)), `CA` (California (CA)), `CO` (Colorado (CO)), and 52 more.
- ZIP Code (`zip_code`, text): The 5-digit ZIP Code, if you have one to check.
- ZIP+4 (`zip_plus4`, text): The 4 digits after the ZIP Code, when known.
- Business name (`firm`, text): The business at the address, up to 50 characters.

**Outputs**

- `ZIPCode` (text): 5-digit ZIP Code
- `ZIPPlus4` (text): The 4 digits after the ZIP Code
- `address` (object): The address as USPS writes it
- `firm` (text): The business at the address
- `found` (true/false): Whether USPS matched the address
- `message` (text): USPS's reason when it found no match, else empty

**Example output**

```json
{
  "ZIPCode": "20500",
  "ZIPPlus4": "0005",
  "address": {
    "ZIPCode": "20500",
    "ZIPPlus4": "0005",
    "city": "WASHINGTON",
    "cityAbbreviation": "WASHINGTON",
    "secondaryAddress": "",
    "state": "DC",
    "streetAddress": "1600 PENNSYLVANIA AVE NW",
    "streetAddressAbbreviation": "1600 PENNSYLVANIA AVE NW",
    "urbanization": ""
  },
  "firm": "",
  "found": true,
  "message": null
}
```

### Standardize address

Check a U.S. address with USPS and get it back as USPS writes it, with its ZIP+4, whether USPS confirms it is deliverable, whether it is a business or vacant, and its county. Give a city and state, or a ZIP Code. An address USPS can't match comes back with found set to false and the reason.

**Inputs**

- Street address (`street_address`, text, required): The building number and street, such as 1600 Pennsylvania Ave NW.
- Apartment or suite (`secondary_address`, text): The apartment, suite or unit, such as Apt 2B. It can also go at the end of the street address.
- City (`city`, text): The city. Give a city and state, or a ZIP Code.
- State (`state`, text): The state. Give a city and state, or a ZIP Code. One of: `AL` (Alabama (AL)), `AK` (Alaska (AK)), `AS` (American Samoa (AS)), `AZ` (Arizona (AZ)), `AR` (Arkansas (AR)), `AA` (Armed Forces Americas (AA)), `AE` (Armed Forces Europe, Middle East, Africa and Canada (AE)), `AP` (Armed Forces Pacific (AP)), `CA` (California (CA)), `CO` (Colorado (CO)), and 52 more.
- ZIP Code (`zip_code`, text): The 5-digit ZIP Code, if known.
- ZIP+4 (`zip_plus4`, text): The 4 digits after the ZIP Code, when known.
- Business name (`firm`, text): The business at the address, up to 50 characters.
- Urbanization (`urbanization`, text): The urbanization name, for Puerto Rico addresses only.

**Outputs**

- `additionalInfo` (object): Delivery details USPS knows about the address
- `address` (object): The address as USPS writes it
- `corrections` (list): What to add for a better match, such as an apartment number
- `firm` (text): The business at the address
- `found` (true/false): Whether USPS matched the address
- `matches` (list): 31 for an exact match
- `message` (text): USPS's reason when it found no match, else empty
- `warnings` (list): USPS's warnings

**Example output**

```json
{
  "additionalInfo": {
    "DPVBusiness": "Y",
    "DPVCMRA": "N",
    "DPVConfirmation": "Y",
    "DPVVacant": "N",
    "business": "Y",
    "carrierRoute": "C000",
    "centralDeliveryPoint": "N",
    "congressDistrict": "AL",
    "countyName": "DISTRICT OF COLUMBIA",
    "deliveryPoint": "00",
    "vacant": "N"
  },
  "address": {
    "ZIPCode": "20500",
    "ZIPPlus4": "0005",
    "city": "WASHINGTON",
    "cityAbbreviation": "WASHINGTON",
    "secondaryAddress": "",
    "state": "DC",
    "streetAddress": "1600 PENNSYLVANIA AVE NW",
    "streetAddressAbbreviation": "1600 PENNSYLVANIA AVE NW",
    "urbanization": ""
  },
  "corrections": [
    {
      "code": "",
      "text": ""
    }
  ],
  "firm": "",
  "found": true,
  "matches": [
    {
      "code": "31",
      "text": "Single Response - exact match"
    }
  ],
  "message": null,
  "warnings": []
}
```
