# Standard Address A single address. Every address is returned in this shape, whatever dataset it came from. US and non-US addresses share the same fields, so an integration reads one format only. * `dataset` identifies where the address came from. Fields a dataset does not carry are returned as an empty string (`""`) * `native` carries the raw dataset record, exactly as the dataset supplies it. Retrieve Address returns it for every dataset except `usps`, whose address already is the USPS record The example below is a US address from the [USPS](/docs/data/usps.md) dataset. An address from any other [dataset](/docs/data.md) has the same fields, and its `native` record carries that dataset's raw fields. ## Example Record Every row links to the field's definition on this page. | Field | Example | Type | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | -------- | | [Address Identifier `id`](#address-identifier) | usps\_V124884241\|1040\|\|0001 | `string` | | [Dataset `dataset`](#dataset) | usps | `string` | | [Country `country`](#country) | United States | `string` | | [ISO Country Code (3) `country_iso`](#iso-country-code-3) | USA | `string` | | [ISO Country Code (2) `country_iso_2`](#iso-country-code-2) | US | `string` | | [Language `language`](#language) | en | `string` | | [Primary Number `primary_number`](#primary-number) | 1040 | `string` | | [Secondary Number `secondary_number`](#secondary-number) | Empty in this example | `string` | | [Plus 4 Code `plus_4_code`](#plus-4-code) | 0001 | `string` | | [First Address Line `line_1`](#first-address-line) | 1040 Waverly Ave | `string` | | [Second Address Line `line_2`](#second-address-line) | Empty in this example | `string` | | [Last Line `last_line`](#last-line) | Holtsville NY 00501-0001 | `string` | | [ZIP Code `zip_code`](#zip-code) | 00501 | `string` | | [ZIP + 4 Code `zip_plus_4_code`](#zip-4-code) | 00501-0001 | `string` | | [Update Key Number `update_key_number`](#update-key-number) | V124884241 | `string` | | [Record Type Code `record_type_code`](#record-type-code) | S | `string` | | [Carrier Route ID `carrier_route_id`](#carrier-route-id) | C000 | `string` | | [Street Pre-Directional Abbreviation `street_pre_directional_abbreviation`](#street-pre-directional-abbreviation) | Empty in this example | `string` | | [Street Name `street_name`](#street-name) | Waverly | `string` | | [Street Suffix Abbreviation `street_suffix_abbreviation`](#street-suffix-abbreviation) | Ave | `string` | | [Street Post Directional Abbreviation `street_post_directional_abbreviation`](#street-post-directional-abbreviation) | Empty in this example | `string` | | [Building or Firm Name `building_or_firm_name`](#building-or-firm-name) | Empty in this example | `string` | | [Address Secondary Abbreviation `address_secondary_abbreviation`](#address-secondary-abbreviation) | Empty in this example | `string` | | [Base Alternate Code `base_alternate_code`](#base-alternate-code) | B | `string` | | [LACS Status Indicator `lacs_status_indicator`](#lacs-status-indicator) | Empty in this example | `string` | | [Government Building Indicator `government_building_indicator`](#government-building-indicator) | Empty in this example | `string` | | [State Abbreviation `state_abbreviation`](#state-abbreviation) | NY | `string` | | [State `state`](#state) | New York | `string` | | [Municipality City State Key `municipality_city_state_key`](#municipality-city-state-key) | Empty in this example | `string` | | [Urbanization City State Key `urbanization_city_state_key`](#urbanization-city-state-key) | Empty in this example | `string` | | [Preferred Last Line City State Key `preferred_last_line_city_state_key`](#preferred-last-line-city-state-key) | V13916 | `string` | | [County Name `county`](#county-name) | Suffolk | `string` | | [City Name `city`](#city-name) | Holtsville | `string` | | [City State Name Abbreviation `city_abbreviation`](#city-state-name-abbreviation) | Empty in this example | `string` | | [Preferred Last Line City State Name `preferred_city`](#preferred-last-line-city-state-name) | Holtsville | `string` | | [City State Name Facility Code `city_state_name_facility_code`](#city-state-name-facility-code) | P | `string` | | [ZIP Classification Code `zip_classification_code`](#zip-classification-code) | U | `string` | | [City State Mailing Name Indicator `city_state_mailing_name_indicator`](#city-state-mailing-name-indicator) | Y | `string` | | [Carrier Route Rate Sortation and Merged 5-Digit Indicator `carrier_route_rate_sortation`](#carrier-route-rate-sortation-and-merged-5-digit-indicator) | C | `string` | | [Finance Number `finance_number`](#finance-number) | `353910` | `number` | | [Congressional District Number `congressional_district_number`](#congressional-district-number) | `2` | `number` | | [County Number `county_number`](#county-number) | `103` | `number` | ```json { "id": "usps_V124884241|1040||0001", "dataset": "usps", "country": "United States", "country_iso": "USA", "country_iso_2": "US", "language": "en", "primary_number": "1040", "secondary_number": "", "plus_4_code": "0001", "line_1": "1040 Waverly Ave", "line_2": "", "last_line": "Holtsville NY 00501-0001", "zip_code": "00501", "zip_plus_4_code": "00501-0001", "update_key_number": "V124884241", "record_type_code": "S", "carrier_route_id": "C000", "street_pre_directional_abbreviation": "", "street_name": "Waverly", "street_suffix_abbreviation": "Ave", "street_post_directional_abbreviation": "", "building_or_firm_name": "", "address_secondary_abbreviation": "", "base_alternate_code": "B", "lacs_status_indicator": "", "government_building_indicator": "", "state_abbreviation": "NY", "state": "New York", "municipality_city_state_key": "", "urbanization_city_state_key": "", "preferred_last_line_city_state_key": "V13916", "county": "Suffolk", "city": "Holtsville", "city_abbreviation": "", "preferred_city": "Holtsville", "city_state_name_facility_code": "P", "zip_classification_code": "U", "city_state_mailing_name_indicator": "Y", "carrier_route_rate_sortation": "C", "finance_number": 353910, "congressional_district_number": 2, "county_number": 103 } ``` ## Key Elements The fields most integrations read. ### Address lines Two lines and a last line identify a delivery point. `line_1` is never empty. * `line_1` string First Address Line The primary delivery line (usually the street address) of the address. Example: `1040 Waverly Ave` * `line_2` string Second Address Line Secondary delivery line of the address. Typically populated if the first line is the firm or building name. Example: Empty in this example * `last_line` string Last Line Final line of the address, comprising city, state or region and postal code. Example: `Holtsville NY 00501-0001` ### City, state and ZIP * `city` string City Name City or town name used for mailing; appears in the last line of the address. Example: `Holtsville` * `state` string State Full name of the state, province or region. Example: `New York` * `state_abbreviation` string State Abbreviation Abbreviated name of the state, province or region. For US addresses this is the 2 character state, territory or armed forces designation ("AA", "AE" or "AP" for APO/FPO/DPO). Example: `NY` * `zip_code` string ZIP Code Postal code identifying the delivery area. For US addresses this is the 5 digit ZIP Code. Example: `00501` * `zip_plus_4_code` string ZIP + 4 Code Nine-digit code that identifies a small geographic delivery area serviceable by a single carrier; appears in the last line of the address on a mail piece. USPS addresses only. Example: `00501-0001` ### Country * `country` string Country Full country names (ISO 3166) Example: `United States` Enum: 248 possible values * `country_iso` string ISO Country Code (3) 3 letter country code (ISO 3166-1) Example: `USA` Enum: 243 possible values * `country_iso_2` string ISO Country Code (2) 2 letter country code (ISO 3166-1) Example: `US` Enum: 243 possible values * `language` string Language Language represented by 2 letter ISO Code (639-1) Example: `en` Enum: 64 possible values ### Identifiers `id` is unique across every dataset and is what a search result carries. `dataset` says which dataset the address came from. * `id` string Address Identifier Global unique internally generated identifier for an address Example: `usps_V124884241|1040||0001` * `dataset` string Dataset Indicates the provenance of an address. Example: `usps` Enum: "paf", "pafw", "pafa", "mr", "nyb", "usps", "ecaf", "ecad", "ab", "abp", "herewe", "heret", "heresa", "hereo", "herena", "heremeas", "heremea", "herem", "herei", "herehk", "hereee", "hereap", "gnaf", "kadaster", "kartverket", "sdfi", "cannar", "fodbosa", "mois", "upujp", "bev", "ban", "swt" ### Native record * `native` object Native Record The raw dataset record backing an address, exactly as the dataset supplies it. One schema per dataset; `dataset` on the record says which. ## USPS Elements The remaining fields carry the USPS breakdown of the address. They are empty for addresses outside the United States. ### Premise * `primary_number` string Primary Number Building, house, rural route, contract box or PO Box number. The numeric or alphanumeric component of an address preceding the street name. Example: `1040` * `secondary_number` string Secondary Number Number of the sub unit, apartment, suite etc. Example: Empty in this example * `address_secondary_abbreviation` string Address Secondary Abbreviation A descriptive code identifying the type of secondary range held in the secondary number field, e.g. apartment, suite or trailer. Example: Empty in this example * `building_or_firm_name` string Building or Firm Name The name of a company, building, apartment complex, shopping center, or other distinguishing secondary address information. Example: Empty in this example * `government_building_indicator` string Government Building Indicator An alphabetic value identifying the type of government agency at the delivery point and/or whether a firm is the only delivery at an address. * 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 Example: Empty in this example Enum: "", "A", "B", "C", "D", "E", "F", "G" ### Street * `street_name` string Street Name The official name of the street as assigned by the local governing authority. Contains the street name only, without directionals (EAST, WEST, etc.) or suffixes (ST, DR, BLVD, etc.). May also contain literals such as PO BOX, GENERAL DELIVERY, USS, PSC or UNIT. Example: `Waverly` * `street_pre_directional_abbreviation` string Street Pre-Directional Abbreviation A geographic direction that precedes the street name. Example: Empty in this example * `street_suffix_abbreviation` string Street Suffix Abbreviation Standard abbreviation for the trailing designator in a street address. Example: `Ave` * `street_post_directional_abbreviation` string Street Post Directional Abbreviation A geographic direction that follows the street name. Example: Empty in this example ### City and ZIP detail * `plus_4_code` string Plus 4 Code 4 digit ZIP add-on code. USPS addresses only. Example: `0001` * `zip_classification_code` string ZIP Classification Code Describes the type of ZIP area a 5-digit ZIP Code serves, e.g. a single educational institution, post office boxes only, or a single address with unusually high mail volume. * 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 Example: `U` Enum: "", "M", "P", "U" * `city_abbreviation` string City State Name Abbreviation A standard 13-character abbreviation for a city/state name. Only used for names longer than 13 characters with a city state mailing name indicator of "Y"; blank otherwise. Example: Empty in this example * `preferred_city` string Preferred Last Line City State Name The default preferred or alternate preferred last-line name for a ZIP Code. Example: `Holtsville` * `preferred_last_line_city_state_key` string Preferred Last Line City State Key An index to the USPS City State product record that provides the preferred last-line name for this address range. Example: `V13916` * `municipality_city_state_key` string Municipality City State Key Municipality City State Key. Currently blank. Example: Empty in this example * `urbanization_city_state_key` string Urbanization City State Key An index to the USPS City State file that provides the urbanization name for this delivery range. Example: Empty in this example * `city_state_name_facility_code` string City State Name Facility Code 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 a non-postal place name. * 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 Example: `P` Enum: "B", "C", "N", "P", "S", "U", "Y", "" * `city_state_mailing_name_indicator` string City State Mailing Name Indicator Specifies whether the city state name can be used as the last line of an 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 Example: `Y` ### County and delivery * `county` string County Name Name of the county, parish or equivalent administrative area. Blank for APO/FPO/DPO addresses. Example: `Suffolk` * `county_number` string | number County Number 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. Blank for APO/FPO/DPO addresses whose record type is "S", "H" or "F". Example: `103` * `congressional_district_number` string | number Congressional District Number A standard value identifying a geographic area within the United States served by a member of the U.S. House of Representatives. Blank for APO/FPO/DPO addresses. If there is only one member of Congress within a state, the code will be "AL" (at large). Example: `2` * `finance_number` string | number Finance Number A code assigned to USPS facilities (primarily Post Offices) to collect cost and statistical data and compile revenue and expense data. Example: `353910` * `carrier_route_id` string Carrier Route ID A 4 character ID identifying the USPS postal route for the address. The first character indicates the route type: * "B" indicates PO Box * "H" indicates highway * "C" indicates city * "G" indicates general * "R" indicates rural Example: `C000` * `carrier_route_rate_sortation` string Carrier Route Rate Sortation and Merged 5-Digit Indicator 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. Example: `C` * `base_alternate_code` string Base Alternate Code Code specifying whether the backing USPS record is a base (preferred) or alternate record. Base records ("B") can represent a range of addresses or an individual address, such as a firm record. Alternate records ("A") are individual delivery points. Base records are generally preferred over alternate records. Government deliveries are only listed on alternate records, with the appropriate government building indicator set. Example: `B` Enum: "A", "B", "" * `lacs_status_indicator` string LACS Status Indicator The Locatable Address Conversion Service (LACS) indicator marks USPS records converted to the LACS system, which lets mailers convert a rural route address to a city-style address so emergency services can locate it. * L = LACS address: the old (usually rural-route) address that has been converted * Blank = Not applicable Example: Empty in this example Enum: "", "L" * `record_type_code` string Record Type Code An alphabetic value identifying the type of USPS record backing the address. * G = General delivery * H = High-rise * F = Firm * S = Street * P = PO Box * R = Rural route/contract * M = Multi-carrier Example: `S` Enum: "G", "H", "F", "S", "P", "R", "M", "" * `update_key_number` string Update Key Number Key that uniquely identifies the source dataset record. For USPS this is the Update Key Number: a database segment code (V1, V2, W1, W2, X1, X2, Y1, Y2, Z1 or Z2) followed by eight alphanumeric characters. It is fixed for the life of the record and is not used in address matching. Example: `V124884241` ## Where addresses come from Every address carries `dataset` and `country_iso`. [Supported Countries](/docs/data/supported-countries.md) lists which dataset serves each country and how fine its coverage is; each dataset page documents the `native` record.