Description

Provides verification and standardization for US addresses. While the API is primarily intended to verify addresses for record keeping and shipping, it is also used for address cleaning or standardizing. If may also be used a geocoder where the latitude and longitude returned are those for the shipping address rather than a parcel centroid or building.

Endpoint

https://api.giraffegeo.com/us-address-verification

Request Parameters

Name Type Max Characters Default Value Description
input_id string 36 blank A unique identifier for this address used in your application; this field will be copied into the output.
street string 64 blank The street line of the address, or the entire address ("freeform" input). Freeform inputs should NOT include any form of country information (like "USA").
street2 string 64 blank Any extra address information (e.g., Leave it on the front porch.)
secondary string 32 blank Apartment, suite, or office number (e.g., "Apt 52" or simply "52"; not "Apt52".)
city string 64 blank The city name
state string 32 blank The state name or abbreviation
zipcode string 16 blank The ZIP Code
lastline string 64 blank City, state, and ZIP Code combined
addressee string 64 blank The name of the recipient, firm, or company at this address
urbanization string 64 blank Only used with Puerto Rico
candidates integer Max Value: 10 1 The maximum number of valid addresses returned when the input is ambiguous
match string 8 strict The match output strategy to be employed for this lookup. Valid values are: strict1, range2, invalid3. Because range and invalid are not compatible with freeform address input, the strict match output strategy will be employed in those cases regardless of the provided match output strategy value.
  1. The API will ONLY return candidates that are valid USPS addresses.
  2. The API will return candidates that are valid USPS addresses, as well as invalid addresses with primary numbers that fall within a valid range for the street.
  3. The API will return a single candidate for every properly submitted address, even if invalid or ambiguous.

Response fields

Field Name Type Definition
input_id varchar(36) Any unique identifier that you use to reference the input address; the output will be identical to the input.
input_index int The order in which this address was submitted with the others (0 if alone)
candidate_index int An input address can match multiple valid addresses. This ties the candidates to the input index. (e.g., "1 Rosedale Street Baltimore Maryland" will return multiple candidates.)
addressee varchar(50) Will usually contain a firm name; intended recipient at an address
delivery_line_1 varchar(50) Contains the first delivery line (usually the street address). This can include any of the following: Primary Number, Street Name, Street Predirection, Street Postdirection, Street Suffix, Secondary Number, Secondary Designator, PMB Designator, PMB Number
delivery_line_2 varchar(50) The second delivery line (if needed). It is common for this field to remain empty, but it may contain a private mailbox number.
last_line varchar(50) City, state, and ZIP Code combined
delivery_point_barcode varchar(12) 12-digit POSTNET barcode; consists of 5-digit ZIP Code, 4-digit add-on code, 2-digit delivery point, and 1-digit check digit.
components Object See "Components" table below.
metadata Object See "Metadata" table below.
analysis Object See "Analysis" table below.

Components

Field Name Type Definition
urbanization varchar(64) Primarily for Puerto Rican addresses; a very important component which contains area, sector, or development within a geographic area; should be included after the name of the recipient
primary_number varchar(30) The house, PO Box, or building number
street_name varchar(64) The name of the street
street_predirection char(16) Directional information before a street name (N, SW, etc.)
street_postdirection char(16) Directional information after a street name (N, SW, etc.)
street_suffix char(16) Abbreviated value describing the street (St, Ave, Blvd, etc.)
secondary_number varchar(32) Apartment or suite number, if any
secondary_designator varchar(16) Describes location within a complex/building (Ste, Apt, etc.)
extra_secondary_number varchar(32) Descriptive information about the location of a building within a campus (e.g., E-5 in "5619 Loop 1604, Bldg E-5, Ste. 101 San Antonio TX")
extra_secondary_designator varchar(16) Description of the location type within a campus (e.g., Bldg, Unit, Lot, etc.)
pmb_designator varchar(16) Private mailbox unit designator (assigned by a CMRA)
pmb_number varchar(16) The private mailbox number, assigned by a CMRA
city_name varchar(64) The USPS-preferred city name for this particular address
default_city_name varchar(64) The default city name for this 5-digit ZIP Code. This field will not be present if the default city name is equal to the value of the city name field.
state_abbreviation char(2) The two-letter state abbreviation
zipcode char(5) The 5-digit ZIP Code
plus4_code char(4) The 4-digit add-on code (more specific than 5-digit ZIP)
delivery_point char(2) The last two digits of the house/box number, unless an "H" record is matched, in which case this is the secondary unit number representing the delivery point information to form the delivery point barcode (DPBC).
delivery_point_check_digit char(1) Correction character, or check digit, for the 11-digit barcode

Metadata

Field Name Type Definition
record_type char(1) Indicates the type of record that was matched. Only given if a DPV match is made.

F -- Firm; the finest level of match available for an address. (e.g., Julie Julia 11300 Center Ave Gilroy CA 95020-9257)

G -- General Delivery; for mail to be held at local post offices. (e.g., General Delivery Provo UT 84601)

H -- High-rise; address contains apartment or building sub-units. (e.g., 1600 Pennsylvania Ave SE Washington DC 20003-3228)

P -- Post Office box; address is a PO Box record type.(e.g., PO Box 4735 Tulsa OK 74159-0735)

R -- Rural Route or Highway Contract; may have box number ranges. (e.g., RR 2 Box 4560 Anasco PR 00610-9393)

S-- Street; address contains a valid primary number range. (e.g., 16990 Monterey Rd Lake Elsinore CA 92530-7529)

[blank] -- No record type because address did not make a valid DPV match (e.g., Julie Julia 11300 Center Ave Gilroy CA 95020-9257)
zip_type varchar(32) Indicates the type of the ZIP Code for the address that was matched. Only given if a 5-digit match is made.

Unique -- The ZIP Code consists of a single delivery point, pertaining to a United States Postal Service customer (like a large business or government agency) that routes all of its own mail internally.

Military -- The ZIP Code pertains to military units and diplomatic organizations, often in foreign locations.

POBox -- The ZIP Code is assigned to a collection of Post Office Boxes.

Standard -- The ZIP Code does not pertain to any of the above categories.
county_fips char(5) The 5-digit county FIPS (Federal Information Processing Standards) code. It is a combination of a 2-digit state FIPS code and a 3-digit county code assigned by the NIST (National Institute of Standards and Technology).
county_name varchar(64) The name of the county the address is in
carrier_route char(4) The postal carrier route for the address
congressional_district char(2) The congressional district to which the address belongs. Output will be two digits from 01 - 53 or "AL." "AL" means that the entire state (or territory) is covered by a single congressional district. These include Alaska, Delaware, Montana, North Dakota, South Dakota, Vermont, Wyoming, Washington DC, Virgin Islands, and other territories.
building_default_indicator char(1) Indicates whether the address is the "default" address for a building; for example, the main lobby
rdi varchar(12) Residential Delivery Indicator (residential or commercial)

Residential -- The address is a residential address.

Commercial -- The address is a commercial address.

[blank] -- This happens when the address is invalid or we don't have enough information to ascertain RDI status.
elot_sequence varchar(4) eLOT (Enhanced Line of Travel) 4-digit sequence number
elot_sort varchar(4) eLOT (Enhanced Line of Travel) product was developed to give mailers the ability to sort their mailings by line of travel sequence.

A --Ascending

D -- Descending

[blank] -- Address not submitted for eLOT
latitude decimal(12,9) The horizontal component used for geographic positioning. It is the angle between 0 (the equator) and +/-90 (north or south) at the poles. It is the first value in an ordered pair of (latitude, longitude). A negative number denotes a location below the equator; a positive number is above the equator. Combining lat/long values enables you to pinpoint addresses on a map.
longitude decimal(12,9) The vertical component used for geographic positioning. It is the angle between 0 (the Prime Meridian) and +/-180 (westward or eastward). It is the second number in an ordered pair of (latitude, longitude). A negative number indicates a location west of Greenwich, England; a positive number east. Combining lat/long values enables you to pinpoint addresses on a map.
precision varchar(18) Indicates the precision of the latitude and longitude values.

Unknown -- Coordinates not known, possibly because address is invalid

None -- Coordinates are not provided for this address. Military addresses such as APO, FPO, and DPO do not provide coordinates.

State -- Reserved for future use

SolutionArea -- Reserved for future use

City -- Reserved for future use

Zip5 -- Accurate to a 5-digit ZIP Code level (least precise)

Zip6 -- Accurate to a 6-digit ZIP Code level

Zip7 -- Accurate to a 7-digit ZIP Code level

Zip8 -- Accurate to an 8-digit ZIP Code level

Zip9 -- Accurate to a 9-digit ZIP Code level (most precise but NOT rooftop level)

Structure -- Reserved for future use

Note: Concerning addresses for which the ZIP9 precision is not available, the ZIP# precision is interpolated based on neighboring addresses. Thus, ZIP7 is an average of all the lat/long coordinates of nearby ZIP Codes that share those first 7 digits.
time_zone varchar(48) Indicates the common name of the time zone associated with the address.

Valid Responses: Alaska, Atlantic, Central, Eastern, Hawaii, Mountain, None, Pacific, Samoa, UTC+9, UTC+10, UTC+11, UTC+12
utc_offset decimal(4,2) Indicates the number of hours the time zone is offset from Universal Time Coordinated (UTC), the international time standard, also known as Greenwich Meridian Time (GMT).

Valid Responses: -11, -10, -9, -8, -7, -6, -5, -4, 0, 9, 10, 11, 12
dst char(5) Indicates if the time zone "obeys," or, in other words, adjusts their clocks forward and back with the seasons. This information is particularly useful to determine time in other time zones with areas that may or may not use daylight saving time - for example, Arizona, Hawaii, and, of all places, Indiana.

true -- Time zone observes daylight saving time.

If dst is absent from the response, then time zone does not observe daylight saving time.