### GET /city-state Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml Returns the city and state corresponding to the given ZIP Code™. ```markdown ### Parameters - **ZIPCode** (string, query, required): This is the 5-digit ZIP code. ### Responses #### 200 - Successful operation. **CityStateResponse** - **city** (string): This is the city name of the address. (example: "Des Moines") - **state** (string): This is two-character state code of the address. (example: "IA") - **ZIPCode** (string): This is the ZIP Code of the address. (example: "50314") **CityStateResponse** #### 400 - A bad request was received. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### 401 - Unauthorized request. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### 403 - Access is denied. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### 429 - Too Many Requests. Too many requests have been received from the client in a short amount of time. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### 503 - Service is unavailable. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### default - Other unanticipated errors that may occur. ### Example Usage ```bash curl -X GET "https://apis.usps.com/addresses/v3/city-state?ZIPCode=string" ``` ``` -------------------------------- ### GET /address Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml Standardizes street addresses including city and street abbreviations as well as providing missing information such as ZIP Code™ and ZIP + 4®. Must specify a street address, a state, and either a city or a ZIP Code™. ```markdown ### Parameters - **firm** (string, query, optional): Firm/business corresponding to the address. - **streetAddress** (string, query, required): The number of a building along with the name of the road or street on which it is located. - **secondaryAddress** (string, query, optional): The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building. For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm). - **city** (string, query, optional): This is the city name of the address. - **state** (string, query, required): The two-character state code of the address. - **urbanization** (string, query, optional): This is the urbanization code relevant only for Puerto Rico addresses. - **ZIPCode** (string, query, optional): This is the 5-digit ZIP code. - **ZIPPlus4** (string, query, optional): This is the 4-digit component of the ZIP+4 code. Using the correct ZIP+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error. ### Responses #### 200 - Successful operation. **AddressResponse** - **firm** (string): This is the firm/business name at the address. - **address** (object): Address fields standard to all locations. - **streetAddress** (string): The number of a building along with the name of the road or street on which it is located. - **streetAddressAbbreviation** (string): This is the abbreviation of the primary street address line for the address. - **secondaryAddress** (string): The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building. For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm). - **cityAbbreviation** (string): This is the abbreviation of the city name for the address. - **city** (string): This is the city name of the address. - **state** (string): The two-character state code. - **ZIPCode** (string): This is the 5-digit ZIP code. - **ZIPPlus4** (string): This is the 4-digit component of the ZIP+4 code. Using the correct ZIP+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error. - **urbanization** (string): An area, sector, or residential development within a geographic area (typically used for addresses in Puerto Rico). - **additionalInfo** (object): Extra information about the request. - **deliveryPoint** (string): A specific set of digits between 00 and 99 is assigned to every address that is combined with the ZIP + 4® Code to provide a unique identifier for every delivery address. A street address does not necessarily represent a single delivery point because a street address such as one for an apartment building may have several delivery points. - **carrierRoute** (string): This is the carrier route code (values unspecified). (example: "C012") - **DPVConfirmation** (string (Y|D|S|N)): The DPV Confirmation indicator identifies whether the address provided maps to a known USPS address record, whether the USPS delivers to the address or not. If the USPS does not deliver to the address, the USPS may deliver to a PO Box instead. `carrierRoute` values of `R777` and `R779`, for example, may require the shipper to ask the recipient where they receive their USPS mail, which may be different than their physical address. * `Y` - Address was DPV confirmed for both primary and (if present) secondary numbers. A value of `Y` does not necessarily imply that USPS delivers to that address. * `D` - Address was DPV confirmed for the primary number only, and the secondary number information was missing. * `S` - Address was DPV confirmed for the primary number only, and the secondary number information was present but not confirmed. * `N` - Both primary and (if present) secondary number information failed to DPV confirm. ("Y"|"D"|"S"|"N") - **DPVCMRA** (string (Y|N)): Indicates if the location is a [Commercial Mail Receiving Agency (CMRA)](https://faq.usps.com/s/article/Commercial-Mail-Receiving-Agency-CMRA). * `Y` - Address was found in the CMRA table. * `N` - Address was not found in the CMRA table. ("Y"|"N") - **business** (string (Y|N)): Indicates whether this is a business address. * `Y` - The address is a business address. * `N` - The address is not a business address. ("Y"|"N") - **centralDeliveryPoint** (string (Y|N)): Central Delivery is for all business office buildings and/or industrial/professional parks. This may include call windows, horizontal locked mail receptacles, and cluster box units. * `Y` - The address is a central delivery point. * `N` - The address is not a central delivery point. ("Y"|"N") - **vacant** (string (Y|N)): Indicates whether the location designated by the address is occupied. * `Y` - The address is not occupied. * `N` - The address is occupied. ("Y"|"N") - **corrections** (array (object)): Codes that indicate how to improve the address input to get a better match. Code `32` will indicate "Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number." The recommended change would be to add additional information, such as an apartment, suite, or box number, to match to a specific address. Code `22` will indicate "Multiple addresses were found for the information you entered, and no default exists." The address could not be resolved as entered and more information would be needed to identify the address. Array items: - **code** (string): The code corresponding to the address correction. - **text** (string): This is the description of the address correction. - **matches** (array (object)): Codes that indicate if an address is an exact match. Code `31` will be returned "Single Response - exact match" indicating that the address was correctly matched to a ZIP+4 record. Array items: - **warnings** (array (string)) **AddressResponse** #### 400 - Bad Request. There is an error in the received request. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### 401 - Unauthorized request. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### 403 - Access is denied. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### 404 - Address Not Found. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### 429 - Too Many Requests. Too many requests have been received from the client in a short amount of time. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### 503 - Service is unavailable. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### default - Other unanticipated errors that may occur. ### Example Usage ```bash curl -X GET "https://apis.usps.com/addresses/v3/address?firm=string&streetAddress=string&secondaryAddress=string&city=string&state=string&urbanization=string&ZIPCode=string&ZIPPlus4=string" ``` ``` -------------------------------- ### Schema: Address Corrections Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml Codes that indicate how to improve the address input to get a better match. Code `32` will indicate "Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number." The recommended change would be to add additional information, such as an apartment, suite, or box number, to match to a specific address. Code `22` will indicate "Multiple addresses were found for the information you entered, and no default exists." The address could not be resolved as entered and more information would be needed to identify the address. ```markdown ## Schema: Address Corrections Codes that indicate how to improve the address input to get a better match. Code `32` will indicate "Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number." The recommended change would be to add additional information, such as an apartment, suite, or box number, to match to a specific address. Code `22` will indicate "Multiple addresses were found for the information you entered, and no default exists." The address could not be resolved as entered and more information would be needed to identify the address. **Type:** array - Array of object - **code** (string): The code corresponding to the address correction. - **text** (string): This is the description of the address correction. ``` -------------------------------- ### GET /zipcode Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml Returns the ZIP Code™ and ZIP + 4® corresponding to the given address, city, and state (use USPS state abbreviations). ```markdown ### Parameters - **firm** (string, query, optional): Firm/business corresponding to the address. - **streetAddress** (string, query, required): The number of a building along with the name of the road or street on which it is located. - **secondaryAddress** (string, query, optional): The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building. For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm). - **city** (string, query, required): This is the city name of the address. - **state** (string, query, required): This is the two-character state code of the address. - **ZIPCode** (string, query, optional): This is the 5-digit ZIP code. - **ZIPPlus4** (string, query, optional): This is the 4-digit component of the ZIP+4 code. Using the correct ZIP+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error. ### Responses #### 200 - Successful operation. **ZIPCodeResponse** - **firm** (string): This is the firm/business name at the address. - **address** (object): Address fields standard to all locations. - **streetAddress** (string): The number of a building along with the name of the road or street on which it is located. - **streetAddressAbbreviation** (string): This is the abbreviation of the primary street address line for the address. - **secondaryAddress** (string): The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building. For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm). - **cityAbbreviation** (string): This is the abbreviation of the city name for the address. - **city** (string): This is the city name of the address. - **state** (string): The two-character state code. - **ZIPCode** (string): This is the 5-digit ZIP code. - **ZIPPlus4** (string): This is the 4-digit component of the ZIP+4 code. Using the correct ZIP+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error. - **urbanization** (string): An area, sector, or residential development within a geographic area (typically used for addresses in Puerto Rico). **ZIPCodeResponse** #### 400 - There is an error in the received request. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### 401 - Unauthorized request. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### 403 - Access is denied. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### 429 - Too Many Requests. Too many requests have been received from the client in a short amount of time. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### 503 - Service is unavailable. **ErrorMessage** - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. **ErrorMessage** #### default - Other unanticipated errors that may occur. ### Example Usage ```bash curl -X GET "https://apis.usps.com/addresses/v3/zipcode?firm=string&streetAddress=string&secondaryAddress=string&city=string&state=string&ZIPCode=string&ZIPPlus4=string" ``` ``` -------------------------------- ### Schema: Address Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml Address fields standard to all locations. ```markdown ## Schema: Address Address fields standard to all locations. **Type:** object - **streetAddress** (string): The number of a building along with the name of the road or street on which it is located. - **streetAddressAbbreviation** (string): This is the abbreviation of the primary street address line for the address. - **secondaryAddress** (string): The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building. For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm). - **cityAbbreviation** (string): This is the abbreviation of the city name for the address. ``` -------------------------------- ### Schema: Address Matches Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml Codes that indicate if an address is an exact match. Code `31` will be returned "Single Response - exact match" indicating that the address was correctly matched to a ZIP+4 record. ```markdown ## Schema: Address Matches Codes that indicate if an address is an exact match. Code `31` will be returned "Single Response - exact match" indicating that the address was correctly matched to a ZIP+4 record. **Type:** array - Array of object - **code** (string) - **text** (string) ``` -------------------------------- ### Schema: City And State Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml Schema definition for CityAndState ```markdown ## Schema: City And State Schema definition for CityAndState **Type:** object - **city** (string): This is the city name of the address. (example: "Des Moines") - **state** (string): This is two-character state code of the address. (example: "IA") - **ZIPCode** (string): This is the ZIP Code of the address. (example: "50314") ``` -------------------------------- ### Schema: Error Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml Standard error message response. ```markdown ## Schema: Error Standard error message response. **Type:** object - **apiVersion** (string): The version of the API that was used and that raised the error. - **error** (object): The high-level error that has occurred as indicated by the status code. - **code** (string): The error status code that has been returned in response to the request. - **message** (string): A human-readable message describing the error. - **errors** (array (object)) Array items: - **status** (string): The status code response returned to the client. - **code** (string): An internal subordinate code used for error diagnosis. - **title** (string): A human-readable title that identifies the error. - **detail** (string): A human-readable description of the error that occurred. - **source** (object): The element that is suspected of originating the error. Helps to pinpoint the problem. - **parameter** (string): The input in the request which caused an error. - **example** (string): An example of a valid value for the input parameter. ``` -------------------------------- ### Security: OAuth Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml The specified APIs accept an access token formatted as a JSON Web Token. The relative path to the OAuth2 version 3 API which supplies this access token is provided below for reference. ```markdown ## Security: OAuth **Description:** The specified APIs accept an access token formatted as a JSON Web Token. The relative path to the OAuth2 version 3 API which supplies this access token is provided below for reference. **Type:** oauth2 **OAuth Flows:** - **clientCredentials**: /oauth2/v3/token - Scopes: addresses - **authorizationCode**: /oauth2/v3/authorize - Scopes: addresses ``` -------------------------------- ### Schema: State Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml The two-character state code. ```markdown ## Schema: State The two-character state code. **Type:** string ``` -------------------------------- ### Schema: Address Additional Information Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml Extra information about the request. ```markdown ## Schema: Address Additional Information Extra information about the request. **Type:** object - **deliveryPoint** (string): A specific set of digits between 00 and 99 is assigned to every address that is combined with the ZIP + 4® Code to provide a unique identifier for every delivery address. A street address does not necessarily represent a single delivery point because a street address such as one for an apartment building may have several delivery points. - **carrierRoute** (string): This is the carrier route code (values unspecified). (example: "C012") - **DPVConfirmation** (string (Y|D|S|N)): The DPV Confirmation indicator identifies whether the address provided maps to a known USPS address record, whether the USPS delivers to the address or not. If the USPS does not deliver to the address, the USPS may deliver to a PO Box instead. `carrierRoute` values of `R777` and `R779`, for example, may require the shipper to ask the recipient where they receive their USPS mail, which may be different than their physical address. * `Y` - Address was DPV confirmed for both primary and (if present) secondary numbers. A value of `Y` does not necessarily imply that USPS delivers to that address. * `D` - Address was DPV confirmed for the primary number only, and the secondary number information was missing. * `S` - Address was DPV confirmed for the primary number only, and the secondary number information was present but not confirmed. * `N` - Both primary and (if present) secondary number information failed to DPV confirm. ("Y"|"D"|"S"|"N") - **DPVCMRA** (string (Y|N)): Indicates if the location is a [Commercial Mail Receiving Agency (CMRA)](https://faq.usps.com/s/article/Commercial-Mail-Receiving-Agency-CMRA). * `Y` - Address was found in the CMRA table. * `N` - Address was not found in the CMRA table. ("Y"|"N") - **business** (string (Y|N)): Indicates whether this is a business address. * `Y` - The address is a business address. * `N` - The address is not a business address. ("Y"|"N") - **centralDeliveryPoint** (string (Y|N)): Central Delivery is for all business office buildings and/or industrial/professional parks. This may include call windows, horizontal locked mail receptacles, and cluster box units. * `Y` - The address is a central delivery point. * `N` - The address is not a central delivery point. ("Y"|"N") - **vacant** (string (Y|N)): Indicates whether the location designated by the address is occupied. * `Y` - The address is not occupied. * `N` - The address is occupied. ("Y"|"N") ``` -------------------------------- ### Schema: Address Response Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml Standardizes street addresses including city and street abbreviations, and provides missing information such as ZIP Code™ and ZIP + 4®. ```markdown ## Schema: Address Response Standardizes street addresses including city and street abbreviations, and provides missing information such as ZIP Code™ and ZIP + 4®. **Type:** object - **firm** (string): This is the firm/business name at the address. - **address** (object): Address fields standard to all locations. - **streetAddress** (string): The number of a building along with the name of the road or street on which it is located. - **streetAddressAbbreviation** (string): This is the abbreviation of the primary street address line for the address. - **secondaryAddress** (string): The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building. For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm). - **cityAbbreviation** (string): This is the abbreviation of the city name for the address. - **city** (string): This is the city name of the address. - **state** (string): The two-character state code. - **ZIPCode** (string): This is the 5-digit ZIP code. - **ZIPPlus4** (string): This is the 4-digit component of the ZIP+4 code. Using the correct ZIP+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error. - **urbanization** (string): An area, sector, or residential development within a geographic area (typically used for addresses in Puerto Rico). - **additionalInfo** (object): Extra information about the request. - **deliveryPoint** (string): A specific set of digits between 00 and 99 is assigned to every address that is combined with the ZIP + 4® Code to provide a unique identifier for every delivery address. A street address does not necessarily represent a single delivery point because a street address such as one for an apartment building may have several delivery points. - **carrierRoute** (string): This is the carrier route code (values unspecified). (example: "C012") - **DPVConfirmation** (string (Y|D|S|N)): The DPV Confirmation indicator identifies whether the address provided maps to a known USPS address record, whether the USPS delivers to the address or not. If the USPS does not deliver to the address, the USPS may deliver to a PO Box instead. `carrierRoute` values of `R777` and `R779`, for example, may require the shipper to ask the recipient where they receive their USPS mail, which may be different than their physical address. * `Y` - Address was DPV confirmed for both primary and (if present) secondary numbers. A value of `Y` does not necessarily imply that USPS delivers to that address. * `D` - Address was DPV confirmed for the primary number only, and the secondary number information was missing. * `S` - Address was DPV confirmed for the primary number only, and the secondary number information was present but not confirmed. * `N` - Both primary and (if present) secondary number information failed to DPV confirm. ("Y"|"D"|"S"|"N") - **DPVCMRA** (string (Y|N)): Indicates if the location is a [Commercial Mail Receiving Agency (CMRA)](https://faq.usps.com/s/article/Commercial-Mail-Receiving-Agency-CMRA). * `Y` - Address was found in the CMRA table. * `N` - Address was not found in the CMRA table. ("Y"|"N") - **business** (string (Y|N)): Indicates whether this is a business address. * `Y` - The address is a business address. * `N` - The address is not a business address. ("Y"|"N") - **centralDeliveryPoint** (string (Y|N)): Central Delivery is for all business office buildings and/or industrial/professional parks. This may include call windows, horizontal locked mail receptacles, and cluster box units. * `Y` - The address is a central delivery point. * `N` - The address is not a central delivery point. ("Y"|"N") - **vacant** (string (Y|N)): Indicates whether the location designated by the address is occupied. * `Y` - The address is not occupied. * `N` - The address is occupied. ("Y"|"N") - **corrections** (array (object)): Codes that indicate how to improve the address input to get a better match. Code `32` will indicate "Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number." The recommended change would be to add additional information, such as an apartment, suite, or box number, to match to a specific address. Code `22` will indicate "Multiple addresses were found for the information you entered, and no default exists." The address could not be resolved as entered and more information would be needed to identify the address. Array items: - **code** (string): The code corresponding to the address correction. - **text** (string): This is the description of the address correction. - **matches** (array (object)): Codes that indicate if an address is an exact match. Code `31` will be returned "Single Response - exact match" indicating that the address was correctly matched to a ZIP+4 record. Array items: - **warnings** (array (string)) ``` -------------------------------- ### Schema: Domestic Address Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml Address fields for US locations ```markdown ## Schema: Domestic Address Address fields for US locations **Type:** object - **streetAddress** (string): The number of a building along with the name of the road or street on which it is located. - **streetAddressAbbreviation** (string): This is the abbreviation of the primary street address line for the address. - **secondaryAddress** (string): The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building. For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm). - **cityAbbreviation** (string): This is the abbreviation of the city name for the address. - **city** (string): This is the city name of the address. - **state** (string): The two-character state code. - **ZIPCode** (string): This is the 5-digit ZIP code. - **ZIPPlus4** (string): This is the 4-digit component of the ZIP+4 code. Using the correct ZIP+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error. - **urbanization** (string): An area, sector, or residential development within a geographic area (typically used for addresses in Puerto Rico). ``` -------------------------------- ### Schema: City and State Response Source: https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_4.yaml The validated ZIP Code™ for a given city and state. ```markdown ## Schema: City and State Response The validated ZIP Code™ for a given city and state. **Type:** object - **city** (string): This is the city name of the address. (example: "Des Moines") - **state** (string): This is two-character state code of the address. (example: "IA") - **ZIPCode** (string): This is the ZIP Code of the address. (example: "50314") ```