Skip to main content

Resolve Address (USA)

GET 
/autocomplete/addresses/:address/usa

Resolves an address autocompletion by its address ID.

Resolved addresses (including global addresses) are returned in a US format (up to 2 address lines) using US nomenclature (like zipcode, state and city).

Request​

Path Parameters

    address stringrequired

    ID of address suggestion

Query Parameters

    api_key API Key

Responses​

Success

Response Headers
    Schema
      code int32required

      Possible values: [2000]

      message stringrequired

      Possible values: [Success]

      result objectrequired
      oneOf
      id IDrequired

      Global unique internally generated identifier for an address

      dataset USA Datasetrequired

      Possible values: [usps]

      Identifies the address as sourced from USPS

      country Countryrequired

      Possible values: [United States, Guam, Puerto Rico]

      Full country names (ISO 3166)

      country_iso ISO Country Code (3)required

      Possible values: [USA, PRI, GUM]

      3 letter country code (ISO 3166-1)

      country_iso_2 ISO Country Code (2)required

      Possible values: [US, PR, GU]

      2 letter country code (ISO 3166-1)

      language Languagerequired

      Possible values: [en]

      Language represented by 2 letter ISO Code (639-1)

      primary_number Primary Numberrequired

      A house, rural route, contract box, or Post Office Box number. The numeric or alphanumeric component of an address preceding the street name. Often referred to as house number.

      secondary_number Secondary Numberrequired

      Number of the sub unit, apartment, suite etc

      plus_4_code Plus 4 Coderequired

      4 digit ZIP add-on code.

      line_1 First Address Linerequired

      The primary delivery line (usually the street address) of the address.

      line_2 Second Address Linerequired

      Secondary delivery line of the address. Typically populated if the first line is the firm or building name.

      last_line Last Linerequired

      Last line of the address comprising of city, state, zip code and zip+4

      zip_code ZIP Coderequired

      A 5-digit code that identifies a specific geographic delivery area. ZIP Codes can represent an area within a state, or a single building or company that has a very high mail volume.

      zip_plus_4_code ZIP + 4 Coderequired

      Nine-digit code that identifies a small geographic delivery area that is serviceable by a single carrier; appears in the last line of the address on a mail piece.

      update_key_number Update Key Numberrequired

      Field that contains a number that uniquely identifies a record; used to identify the base record to which an add or delete transaction is being directed. The Update Key Number field is used only when applying transactions to the base file; it is not used in address matching and remains fixed for the life of the record. The field is alphanumeric and consists of the database segment code (V1, V2, W1, W2, X1, X2, Y1, Y2, Z1, or Z2) and eight characters containing an alphanumeric value ranging from 00000001 to AAAAAAAA.

      record_type_code Record Type Coderequired

      Possible values: [G, H, F, S, P, R, M, ``]

      An alphabetic value that identifies the type of data in the record. - G = General delivery (5-Digit ZIP, ZIP + 4, and Carrier Route products) - H = High-rise (ZIP + 4 only) - F = Firm (ZIP + 4 only) - S = Street (5-Digit ZIP, ZIP + 4, and Carrier Route products) - P = PO Box (5-Digit ZIP, ZIP + 4, and Carrier Route products) - R = Rural route/contract (5-Digit ZIP, ZIP + 4, and Carrier Route products) - M = Multi-carrier (Carrier Route product only)

      carrier_route_id Carrier Route IDrequired

      A 4 character ID identifying the postal route for the address. The first character indicates the route type. Specifically:

      • "B" indicates PO Box
      • "H" indicates highway
      • "C" indicates city
      • "G" indicates general
      • "R" indicates rural
      street_pre_directional_abbreviation Street Pre-Directional Abbreviationrequired

      A geographic direction that precedes the street name.

      street_name Street Namerequired

      The official name of a street as assigned by a local governing authority. The Street Name field contains only the street name and does not include directionals (EAST, WEST, etc.) or suffixes (ST, DR, BLVD, etc.). This element may also contain literals, such as PO BOX, GENERAL DELIVERY, USS, PSC, or UNIT.

      street_suffix_abbreviation Street Suffix Abbreviationrequired

      Code that is the standard USPS abbreviation for the trailing designator in a street address.

      street_post_directional_abbreviation Street Post Directional Abbreviationrequired

      A geographic direction that follows the street name.

      building_or_firm_name Building or Firm Namerequired

      The name of a company, building, apartment complex, shopping center, or other distinguishing secondary address information. This field is normally used with firm and highrise records but may also contain literals such as “Postmaster” or “United States Postal Service.”

      address_secondary_abbreviation Address Secondary Abbreviationrequired

      A descriptive code used to identify the type of address secondary range information in the Address Secondary Range field. This code may be useful in address matching, e.g., the secondary address numbers may indicate apartment, suite, or trailer numbers.

      base_alternate_code Base Alternate Coderequired

      Possible values: [A, B, ``]

      Code that specifies whether a record is a base (preferred) or alternate record. Base records (represented as "B") can represent a range of addresses or an individual address, such as a firm record, while alternate records (represented as "A") are individual delivery points. Base records are generally preferred over alternate records. Government deliveries will only be listed on alternate records with the appropriate government building indicator (federal, state, or city) set.

      lacs_status_indicator LACS Status Indicatorrequired

      Possible values: [``, L]

      The Locatable Address Conversion Service (LACS) indicator describes records that have been converted to the LACS system (a product/system in a different USPS® product line that allows mailers to identify and convert a rural route address to a city-style address). Rural route and some city addresses are being modified to city-style addresses so that emergency services (e.g., ambulances, police) can find these addresses more efficiently.

      • L = LACS address: The old (usually rural-route) address that has been converted for the LACS system.
      • Blank = Not applicable
      government_building_indicator Government Building Indicatorrequired

      Possible values: [``, A, B, C, D, E, F, G]

      An alphabetic value that identifies the type of government agency at the delivery point and/or whether a firm is the only delivery at an address. For this purpose, "address" is defined as the complete delivery line (e.g., complete street address and, if included as part of the firm record, the secondary abbreviation and/or address secondary number).

      • A = City government building—alternates only
      • B = Federal government building—alternates only
      • C = State government building—alternates only
      • D = Firm only—base and alternates
      • E = City government building and firm only—alternates only
      • F = Federal government building and firm only—alternates only
      • G = State government building and firm only—alternates only
      state_abbreviation State Abbreviationrequired

      A 2-character abbreviation for the name of a state, U.S. territory, or armed forces ZIP Code designation. If APO/FPO/DPO, then the state abbreviation will be “AA,” “AE,” or “AP.”

      state Staterequired

      Full name of a state, U.S. territory, or armed forces ZIP Code designation.

      municipality_city_state_key Municipality City State Keyrequired

      Municipality City State Key. Currently blank.

      urbanization_city_state_key Urbanization City State Keyrequired

      An index to the City State file that provides the urbanization name for this delivery range.

      preferred_last_line_city_state_key Preferred Last Line City State Keyrequired

      In the Carrier Route, Five-Digit ZIP Code, Delivery Statistics, and ZIP + 4 products, an index to the City State product record that provides the preferred last-line name for this address range. In the City State product, the preferred last line city/state key contains the key value of a City State product record that has the default preferred or alternate preferred last-line key for a given ZIP Code.

      county County Namerequired

      The name of the county or parish in which the 5-digit ZIP Code resides. If APO/FPO/DPO, then the county name will be blank.

      city City Namerequired

      A valid city name for mailing purposes; appears in the last line of an address on a mail piece.

      city_abbreviation City State Name Abbreviationrequired

      A standard 13-character abbreviation for a city/state name. This field is only used for names that are greater than 13 characters in length and have a city/state mailing name indicator of "Y." If the field is longer than 13 characters and the city/state mailing name indicator is "N," the field will be blank.

      preferred_city Preferred Last Line City State Namerequired

      Field that contains the default preferred or alternate preferred last-line name for a ZIP Code.

      city_state_name_facility_code City State Name Facility Coderequired

      Possible values: [B, C, N, P, S, U, Y, ``]

      The type of locale identified in the city/state name. The facility may be a USPS facility, such as a post office, station, or branch, or it may be a non-postal place name. City/state name facility codes include the following:

      • B = Branch
      • C = Community post office (CPO)
      • N = Non-postal community name, former USPS facility, or place name
      • P = Post Office
      • S = Station
      • U = Urbanization
      zip_classification_code ZIP Classification Coderequired

      Possible values: [``, M, P, U]

      A field that describes the type of ZIP area that a 5-digit ZIP Code serves, e.g., a single educational institution, post office boxes only, or a single address that has unusually high mail volume or many different addresses.

      • M = Military ZIP Code
      • P = ZIP Code having only Post Office Boxes
      • U = Unique ZIP Code (ZIP assigned to a single organization)
      • Blank = Standard ZIP with many addresses assigned to it
      city_state_mailing_name_indicator City State Mailing Name Indicatorrequired

      Specifies whether or not the city state name can be used as a last line of address on a mail piece.

      • "Y = City/state name is a USPS-approved mailing name."
      • "N = City/state name is not approved for mailing purposes."
      carrier_route_rate_sortation Carrier Route Rate Sortation and Merged 5-Digit Indicatorrequired

      Identifies where automation Carrier Route rates are available and where the commingling of automation and non-automation mail, including Enhanced Carrier Routes and 5-digit presort, on the same pallet or in the same container is allowed.

      finance_number objectrequired

      A code assigned to Postal Service facilities (primarily Post Offices) to collect cost and statistical data and compile revenue and expense data.

      oneOf
    • string

      Empty string "" if not available

      • congressional_district_number objectrequired

      A standard value identifying a geographic area within the United States served by a member of the U.S. House of Representatives. If Army/Air Force (APO), Fleet Post Office (FPO), or Diplomatic/Defense Post Office (DPO), this field will be blank. If there is only one member of Congress within a state, the code will be "AL" (at large).

      oneOf
    • string

      Empty string "" if not available

      • county_number objectrequired

      The Federal Information Processing Standard (FIPS) code assigned to a given county or parish within a state. In Alaska, it identifies a region within the state. If APO/FPO/DPO, and the record type is “S,” “H,” or “F,” the county number will be blank.

      oneOf
    • string

      Empty string "" if not available

    Loading...