# Retrieve Address **GET** `/v1/autocomplete/addresses/{address}/usa` Returns the full address for an autocomplete suggestion id. This is the charged step of address autocomplete. A successful retrieval decrements your lookup balance. An id which resolves to no address returns `404`. Every address comes back in one US-shaped format, whatever country or dataset it came from: up to two address lines and US field names such as `zip_code`, `state` and `city`. ## Example request **URL** ```http https://api.addresszen.com/v1/autocomplete/addresses/usps_V118834572|310||3191/usa?api_key=ak_test ``` **curl** ```bash curl -G 'https://api.addresszen.com/v1/autocomplete/addresses/usps_V118834572|310||3191/usa' \ -d 'api_key=ak_test' ``` **JavaScript** ```javascript const response = await fetch( 'https://api.addresszen.com/v1/autocomplete/addresses/usps_V118834572%7C310%7C%7C3191/usa?' + new URLSearchParams({ api_key: 'ak_test', }) ); const { result } = await response.json(); ``` **Python** ```python import requests response = requests.get( "https://api.addresszen.com/v1/autocomplete/addresses/usps_V118834572%7C310%7C%7C3191/usa", params={ "api_key": "ak_test", }, ) result = response.json()["result"] ``` **Ruby** ```ruby require "net/http" require "json" uri = URI("https://api.addresszen.com/v1/autocomplete/addresses/usps_V118834572%7C310%7C%7C3191/usa") uri.query = URI.encode_www_form(api_key: "ak_test") result = JSON.parse(Net::HTTP.get(uri))["result"] ``` **PHP** ```php "ak_test", ]) ); $result = json_decode($response, true)["result"]; ``` ## Example response **200 OK** ```json { "code": 2000, "message": "Success", "result": { "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, "native": { "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 } } } ``` ## Path parameters * `address` string **ID of address suggestion** ID of address suggestion provided by the API to fully retrieve. Example: `usps_V118834572|310||3191` ## Query parameters * `api_key` string optional **API Key** Your unique identifier that allows access to our APIs. Begins `ak_`. Available from your dashboard. Example: `ak_test` * `licensee` string optional **Licensee Key** Uniquely identifies a licensee. Example: `sl_hk71kco54zGSGvF9eXXrvvnMOLLNh` * `filter` string optional **Restrict Result Fields** Comma separated whitelist of address elements to return. E.g. `filter=line_1,line_2,line_3` returns only the `line_1`, `line_2` and `line_3` address elements in your response. Example: `line_1,line_2,line_3` * `tags` string optional **Tags** A comma separated list of tags to query over. Useful if you want to specify the circumstances in which the request was made. If you specify multiple tags, the response comprises only requests that satisfy all of them. Searching `"foo,bar"` queries only requests tagged both `"foo"` and `"bar"`. Example: `foo,bar` ## Response `result` is a single flat `Address` record in US format (up to two address lines, `zip_code`, `state`, `city`). Its `native` field carries the raw dataset record the address came from; follow a dataset link for that record's complete field list. The record sits inside the standard `{ result, code, message }` envelope; see the [API reference](/docs/api/api-reference.md) for the wrapper format. * `result` object * `id` string Global unique internally generated identifier for an address * `dataset` string Indicates the provenance of an address. Values: "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" * `country_iso` string 3 letter country code (ISO 3166-1) Values: 243 possible values * `country_iso_2` string 2 letter country code (ISO 3166-1) Values: 243 possible values * `country` string Full country names (ISO 3166) Values: 248 possible values * `language` string Language represented by 2 letter ISO Code (639-1) Values: 64 possible values * `primary_number` string Building, house, rural route, contract box or PO Box number. The numeric or alphanumeric component of an address preceding the street name. * `secondary_number` string Number of the sub unit, apartment, suite etc. * `plus_4_code` string 4 digit ZIP add-on code. USPS addresses only. * `line_1` string The primary delivery line (usually the street address) of the address. * `line_2` string Secondary delivery line of the address. Typically populated if the first line is the firm or building name. * `last_line` string Final line of the address, comprising city, state or region and postal code. * `zip_code` string Postal code identifying the delivery area. For US addresses this is the 5 digit ZIP Code. * `zip_plus_4_code` string 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. * `update_key_number` string 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. * `record_type_code` string 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 Values: "G", "H", "F", "S", "P", "R", "M", "" * `carrier_route_id` string 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 * `street_pre_directional_abbreviation` string A geographic direction that precedes the street name. * `street_name` string 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. * `street_suffix_abbreviation` string Standard abbreviation for the trailing designator in a street address. * `street_post_directional_abbreviation` string A geographic direction that follows the street name. * `building_or_firm_name` string The name of a company, building, apartment complex, shopping center or other distinguishing secondary address information. * `address_secondary_abbreviation` string A descriptive code identifying the type of secondary range held in the secondary number field, e.g. apartment, suite or trailer. * `base_alternate_code` string 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. Values: "A", "B", "" * `lacs_status_indicator` string 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 Values: "", "L" * `government_building_indicator` string 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 Values: "", "A", "B", "C", "D", "E", "F", "G" * `state_abbreviation` string 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). * `state` string Full name of the state, province or region. * `municipality_city_state_key` string Municipality City State Key. Currently blank. * `urbanization_city_state_key` string An index to the USPS City State file that provides the urbanization name for this delivery range. * `preferred_last_line_city_state_key` string An index to the USPS City State product record that provides the preferred last-line name for this address range. * `county` string Name of the county, parish or equivalent administrative area. Blank for APO/FPO/DPO addresses. * `city` string City or town name used for mailing; appears in the last line of the address. * `city_abbreviation` string 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. * `preferred_city` string The default preferred or alternate preferred last-line name for a ZIP Code. * `city_state_name_facility_code` string 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 Values: "B", "C", "N", "P", "S", "U", "Y", "" * `zip_classification_code` string 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 Values: "", "M", "P", "U" * `city_state_mailing_name_indicator` string 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 * `carrier_route_rate_sortation` string 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` one of * `congressional_district_number` one of * `county_number` one of * `native` NativeRecord optional