Validate - POST

Validate and standardize US postal addresses individually or in batches. Submit up to 100 addresses in a single request and receive standardized, componentized address candidates for each.

Resource URL

https://www.mapquestapi.com/address/v1/validate

Resource Information

Response Formats	JSON
Authentication	Yes (Requires Key)
Rate Limited	Yes

Request Parameters

Request Parameter	Description	Required
key	The API Key, which is needed to make requests to MapQuest services.	Yes

Request Body

The request body must be JSON (Content-Type: application/json). It is a JSON object containing an addresses array. Limits: 1-100 addresses per request, and a maximum request size of 32 KB.

Field	Type	Description	Required
addresses	object[]	Array of 1-100 address objects to validate. See the Address object below.	true
options	object	Request-level options. Defaults to { "maxCandidates": 1 }.	false
options.maxCandidates	integer	Maximum number of candidates to return per address. Range 1-10. Default 1.	false

Address object

Each address is provided either as a freeform string (q) or as individual components. The two styles are mutually exclusive.

Field	Type	Description	Required
q	string (max 100)	Freeform address in a single string. Mutually exclusive with the component fields below. Example: 1600 Pennsylvania Ave NW, Washington DC 20500.	true, if the address is not provided as components (street + locality + region, or street + postcode)
street	string (max 50)	Street line (number, name, directionals, suffix). Mutually exclusive with q. Example: 1600 Pennsylvania Ave NW.	true, if q is not provided
secondary	string (max 32)	Apartment, suite, or unit (e.g. Apt 200).	false
locality	string (max 64)	City or town name. Example: Washington.	true, if q is not provided and postcode is omitted (street + locality + region is the matchable combination)
region	string (max 32)	State name or two-letter abbreviation. Example: DC.	true, if q is not provided and postcode is omitted (street + locality + region is the matchable combination)
postcode	string (max 16)	ZIP Code (5-digit or ZIP+4). Example: 20500.	true, if q is not provided and locality/region are omitted (street + postcode is the matchable combination)
urbanization	string (max 64)	Puerto Rico only. Neighborhood used to disambiguate duplicate street names.	false
country	string	Country code. Only US is supported. Defaults to US.	false

Each address must supply one matchable combination:

• q (freeform), or
• street + locality + region, or
• street + postcode.

Supplying q together with any component field, or including unrecognized fields (in an address, in options, or at the top level), returns 400.

Response Object

On success (200), the response is a JSON object with an options block and a results array:

{
  "options": { "maxCandidates": 10 },
  "results": [
    {
      "input": { /* the address you submitted, echoed back */ },
      "candidates": [ /* standardized candidates, or [] if none */ ]
    }
  ]
}

Field	Type	Description
options.maxCandidates	integer	The effective maxCandidates value applied to the request.
results	object[]	One entry per submitted address, in the same order as the request.
results[].input	object	The submitted address, echoed verbatim, so you can correlate results without a separate id. Fields you did not supply (such as a defaulted country) are not added to the echo.
results[].candidates	object[]	Standardized candidate for this input. Empty ([]) when no match is found.

Only non-blank fields appear on each candidate. Any field for which there is no value is omitted rather than returned as null or an empty string.

Candidate object

Field	Type	Description	Example
street	string	Standardized street line, excluding any secondary unit.	1555 Blake St
secondary	string	Standardized secondary line (unit / mailbox), when present.	Apt 200
postcode	string	5-digit ZIP, or ZIP+4 when available.	80202-1361
locality	string	Standardized city name.	Denver
region	string	Two-letter state abbreviation.	CO
urbanization	string	Puerto Rico only. Neighborhood name, when present.	Urb Los Olmos
country	string	Always US.	US
type	string	USPS record type code describing the kind of delivery point. One of F, G, H, P, R, S — see Record type (type).	H
components	object	Parsed subcomponents of the standardized address (see below).	-
metadata	object	Address metadata and delivery analysis (see below).	-

components

The parsed pieces of the standardized address. The candidate root already carries the printable street and secondary lines; components breaks them into individual parts.

Field	Type	Description	Example
components.street.number	string	Primary/house number.	1555
components.street.predirection	string	Leading directional (e.g. N, SW).	N
components.street.postdirection	string	Trailing directional (e.g. NW).	NW
components.street.name	string	Street name.	Blake
components.street.suffix	string	Street suffix (e.g. Ave, St).	St
components.secondary.type	string	Secondary unit designator (e.g. Apt, Ste).	Apt
components.secondary.number	string	Secondary unit number.	200
components.secondary.subType	string	Additional secondary designator.	Bldg
components.secondary.subNumber	string	Additional secondary number.	4
components.mailbox.type	string	Private mailbox designator (e.g. PMB).	PMB
components.mailbox.number	string	Private mailbox number.	12
components.postcode.primary	string	5-digit ZIP.	80202
components.postcode.extension	string	ZIP+4 extension.	1361

metadata

Address metadata and delivery-point analysis. Binary indicators are booleans; footnote fields are short standardized USPS/CASS code strings — see Code reference for the meaning of every code.

Field	Type	Description	Example
metadata.fips	string	5-digit county FIPS code (2-digit state + 3-digit county).	08031
metadata.county	string	County name.	Denver
metadata.residential	boolean	true if residential, false if commercial. Omitted when unknown.	false
metadata.timezone	string	IANA time zone identifier.	America/Denver
metadata.dpv.match	boolean	true only when the address is confirmed exactly as provided; false for all other outcomes (e.g. missing/unrecognized secondary, or not confirmed).	true
metadata.dpv.footnotes	string	Delivery-point footnote codes describing the match result (2-character USPS codes, concatenated). See DPV footnotes (dpv.footnotes).	AABB
metadata.dpv.cmra	boolean	true if the address is a Commercial Mail Receiving Agency (private mailbox). Omitted when unknown.	false
metadata.dpv.vacant	boolean	true if the address is marked vacant. Omitted when unknown.	false
metadata.dpv.active	boolean	true if the address is an active delivery point; false if it is not currently receiving delivery. Omitted when unknown.	true
metadata.footnotes	string	Change/correction footnote codes (#-delimited) describing standardizations applied to the input (USPS codes). See Change footnotes (footnotes).	N#

Code reference

Several candidate fields carry standardized USPS/CASS codes. This section is the exhaustive reference for every code these fields can return. All codes are USPS standards (CASS™ / DPV®); they are passed through unchanged from the underlying postal data.

Record type (type)

A single-character code describing the kind of delivery point the candidate represents.

Code	Meaning
F	Firm — a business with its own assigned delivery point.
G	General Delivery — held for pickup at the post office.
H	High-rise — an address within a building broken out by unit/floor.
P	PO Box — a post office box.
R	Rural Route / Highway Contract — rural route or highway contract delivery.
S	Street — a standard street-style delivery address.

DPV footnotes (dpv.footnotes)

Delivery Point Validation (DPV) footnotes describe the outcome of confirming the address against USPS delivery data. Each footnote is a 2-character code; multiple codes are concatenated into one string (e.g. AABB, AABBCC), and up to 14 may be present.

Code	Meaning
AA	Input address matched to the ZIP+4 file (all components valid).
A1	Input address not matched to the ZIP+4 file (not in USPS data).
BB	Input address matched to DPV (all components, entire address valid).
CC	Input address secondary number not recognized (present but not required).
C1	Input address secondary number missing or not recognized (required).
F1	Input address matched to a military or diplomatic address.
G1	Input address matched to a general delivery address.
M1	Input address primary number missing.
M3	Input address primary number invalid.
N1	Input address matched but missing a required secondary number.
PB	Input address matched to PO Box style, delivered street-style.
P1	Input address PO/RR/HC box number missing.
P3	Input address PO/RR/HC box number invalid.
RR	Input address matched to CMRA and confirmed with a private mailbox (PMB).
R1	Input address matched to CMRA but not confirmed with a PMB.
R7	Confirmed as a valid address that does not currently receive street delivery.
TA	Input address matched after dropping a trailing alpha character from the primary number.
U1	Input address matched to a unique ZIP Code.

Common combinations you may see: AABB, AABBCC, AAC1, AAM1, AAM3, AAN1, AABBR1.

Change footnotes (footnotes)

Change footnotes describe standardizations or corrections applied to the input during matching. Each footnote is a code ending in #, and multiple codes are concatenated (#-delimited), e.g. N# or A#N#.

Code	Meaning
A#	Corrected ZIP Code.
B#	Corrected the city/state spelling.
C#	Invalid city / state / ZIP Code.
D#	No ZIP+4 assigned; unable to determine ZIP+4.
E#	Same ZIP+4 applies to multiple ZIP Codes.
F#	Address could not be found in the national ZIP+4 file.
G#	Used addressee (firm) data in the match.
H#	Address missing a secondary number (required for a complete match).
I#	Insufficient or incorrect address data.
J#	Dual address (two valid delivery addresses in the input).
K#	Matched a cardinal rule (directional) address.
L#	Changed an address component (abbreviation, spelling, etc.).
LL#	Address flagged for LACSLink conversion.
LI#	Address flagged for LACSLink but not converted.
M#	Corrected the street spelling.
N#	Fixed the abbreviations in the address (e.g. Avenue → Ave).
O#	Multiple ZIP+4s matched; lowest was used.
P#	A better address exists than the one matched.
Q#	Matched a unique ZIP Code.
R#	No match; an EWS (Early Warning System) match is expected soon.
S#	Unrecognized secondary address information.
T#	Magnet-street syndrome; multiple possible responses.
U#	Unofficial (vanity) city name used in the input.
V#	Unverifiable city / state.
W#	Invalid delivery address (a PO Box or General Delivery is required).
X#	Default match within a unique ZIP Code.
Y#	Matched a military address.
Z#	Matched using the ZIPMOVE product (address moved to a new ZIP+4).

Error Responses

Errors are returned as application/problem+json.

Status	Description
400	The request body is invalid (bad shape, unknown field, missing matchable combination, non-US country, q combined with components, or over 100 addresses).
403	Address validation is not available for this account.
413	The request is too large.
422	The request could not be processed as submitted.
429	Too many requests. Retry later.
502	The validation service is temporarily unavailable. Retry.
504	The validation service timed out. Retry.

Example Request

POST https://www.mapquestapi.com/address/v1/validate?key=KEY

Request Body

{
  "addresses": [
    {
      "street": "1555 Blake St",
      "secondary": "Apt 200",
      "locality": "Denver",
      "region": "CO",
      "postcode": "80202"
    },
    {
      "q": "1300 Canyon Blvd, Boulder, CO 80302"
    },
    {
      "street": "123 Calle Uno",
      "urbanization": "Urb Los Olmos",
      "locality": "Ponce",
      "region": "PR",
      "postcode": "00731",
      "country": "US"
    },
    {
      "q": "an address that will not match"
    }
  ],
  "options": {
    "maxCandidates": 10
  }
}

Example Response

200 OK

{
  "options": {
    "maxCandidates": 10
  },
  "results": [
    {
      "input": {
        "street": "1555 Blake St",
        "secondary": "Apt 200",
        "locality": "Denver",
        "region": "CO",
        "postcode": "80202"
      },
      "candidates": [
        {
          "street": "1555 N Blake St NW",
          "secondary": "Apt 200 Bldg 4 PMB 12",
          "postcode": "80202-1361",
          "locality": "Denver",
          "region": "CO",
          "country": "US",
          "type": "H",
          "components": {
            "street": {
              "number": "1555",
              "predirection": "N",
              "postdirection": "NW",
              "name": "Blake",
              "suffix": "St"
            },
            "secondary": {
              "type": "Apt",
              "number": "200",
              "subType": "Bldg",
              "subNumber": "4"
            },
            "mailbox": {
              "type": "PMB",
              "number": "12"
            },
            "postcode": {
              "primary": "80202",
              "extension": "1361"
            }
          },
          "metadata": {
            "fips": "08031",
            "county": "Denver",
            "residential": false,
            "timezone": "America/Denver",
            "dpv": {
              "match": true,
              "footnotes": "AABB",
              "cmra": false,
              "vacant": false,
              "active": true
            },
            "footnotes": "N#"
          }
        }
      ]
    },
    {
      "input": {
        "q": "1300 Canyon Blvd, Boulder, CO 80302"
      },
      "candidates": [
        {
          "street": "1300 Canyon Blvd",
          "postcode": "80302-6741",
          "locality": "Boulder",
          "region": "CO",
          "country": "US",
          "type": "S",
          "components": {
            "street": {
              "number": "1300",
              "name": "Canyon",
              "suffix": "Blvd"
            },
            "postcode": {
              "primary": "80302",
              "extension": "6741"
            }
          },
          "metadata": {
            "fips": "08013",
            "county": "Boulder",
            "residential": false,
            "timezone": "America/Denver",
            "dpv": {
              "match": true,
              "footnotes": "AABB",
              "cmra": false,
              "vacant": false,
              "active": false
            }
          }
        }
      ]
    },
    {
      "input": {
        "street": "123 Calle Uno",
        "urbanization": "Urb Los Olmos",
        "locality": "Ponce",
        "region": "PR",
        "postcode": "00731",
        "country": "US"
      },
      "candidates": [
        {
          "street": "123 Calle Uno",
          "postcode": "00731-1504",
          "locality": "Ponce",
          "region": "PR",
          "urbanization": "Urb Los Olmos",
          "country": "US",
          "type": "S",
          "components": {
            "street": {
              "number": "123",
              "name": "Calle Uno"
            },
            "postcode": {
              "primary": "00731",
              "extension": "1504"
            }
          },
          "metadata": {
            "fips": "72113",
            "county": "Ponce",
            "residential": true,
            "timezone": "America/Puerto_Rico",
            "dpv": {
              "match": true,
              "footnotes": "AABB",
              "cmra": false,
              "vacant": false,
              "active": true
            },
            "footnotes": "N#"
          }
        }
      ]
    },
    {
      "input": {
        "q": "an address that will not match"
      },
      "candidates": []
    }
  ]
}