Skip to content
PostGrid PostGrid
Get started
API Reference
Address Verification

Verify

address_verification.verify(AddressVerificationVerifyParams**kwargs) -> AddressVerificationVerifyResponse
POST/v1/addver/verifications
  1. Structured Address — Verify and standardize a structured address (e.g., with line1, city, etc.).
  2. Freeform Address — Verify and standardize a freeform address written on one line. For best results, append the ISO 2-letter country code (e.g., US, CA) to the end of the line.
  • Specifying includeDetails=true will provide additional output as documented in the Details schema.
  • Uses 1 lookup for verification, and 1 more if geocoding (unless your contract says otherwise).
ParametersExpand Collapse
address: str

The address you want to verify, written on a single line.

geocode: Optional[bool]
include_details: Optional[bool]
proper_case: Optional[bool]
ReturnsExpand Collapse
class AddressVerificationVerifyResponse: …
data: Data
city: str

The city name of the address.

country: str

The country code of the address.

line1: str

The first line of the address.

postal_or_zip: str

The postal code or ZIP code of the address.

province_or_state: str

The province or state of the address.

country_name: Optional[str]

The country name of the address.

details: Optional[DataDetails]

If you supply includeDetails=true as a query parameter, we will also populate an additional details field that follows the Address Details schema.

box_id: Optional[str]

PO Box ID

county: Optional[str]

County in the United States (US address only)

county_num: Optional[str]

FIPS code for county (US address only)

delivery_installation_area_name: Optional[str]

Delivery installation area name

delivery_installation_qualifier: Optional[str]

Delivery installation qualifier

delivery_installation_type: Optional[str]

Delivery installation type

extra_info: Optional[str]

Any extra information relevant to the address

post_direction: Optional[str]

The post-direction of the street (after the street name, US addresses only)

pre_direction: Optional[str]

The pre-direction of the street (before the street name, US addresses only)

residential: Optional[bool]

Indicates that the address is residential (US address only)

rural_route_number: Optional[str]

Rural route number

rural_route_type: Optional[str]

Rural route type

street_direction: Optional[str]

The direction of the street (N, S, E, W, etc)

street_name: Optional[str]

Name of the street where the address is located

street_number: Optional[str]

Street number (e.g. the 20 in 20 Bay St)

street_type: Optional[str]

Type of the street (DR, ST, BLVD, etc)

suite_id: Optional[str]

The unit number/name

suite_key: Optional[str]

The suite key

us_census_block_number: Optional[str]

US Census block number

us_census_cmsa: Optional[str]

US Census consolidated metropolitan statistical area

us_census_ma: Optional[str]

US Census metropolitan area

us_census_msa: Optional[str]

US Census metropolitan statistical area

us_census_pmsa: Optional[str]

US Census primary metropolitan statistical area

us_census_tract_number: Optional[str]

US Census tract number

us_congressional_district_number: Optional[str]

US congressional district number

us_has_daylight_savings: Optional[bool]

True if address location recognizes DST

us_mailing_check_digit: Optional[str]

PostNet barcode digit

us_mailings_carrier_route: Optional[str]

4-character code assigned to mail delivery route within a 5 digit zip code

us_mailings_default_flag: Optional[bool]

True if US address matches a high-rise default or rural route default in the USPS data

us_mailings_delivery_point: Optional[str]

Unique USPS identifier for the delivery point

us_mailings_dpv_confirmation_indicator: Optional[str]

See USPS DPV

us_mailings_dpv_crma_indicator: Optional[str]

Y if this is a commercial mail receiving agency, N otherwise

us_mailings_dpv_footnote1: Optional[str]

See USPS DPV

us_mailings_dpv_footnote2: Optional[str]

See USPS DPV

us_mailings_dpv_footnote3: Optional[str]

See USPS DPV

us_mailings_elot_asc_desc: Optional[str]

A for ascending, D for descending

us_mailings_elot_sequence_number: Optional[str]

eLOT sequence number

us_mailings_ews_flag: Optional[str]

Y if address is in early warning system database

us_mailings_lacs_flag: Optional[str]

Y if address converted by LACS

us_mailings_lacs_return_code: Optional[str]

Corresponds to USPS LACSLink return code

us_mailings_record_type_code: Optional[str]

See USPS DPV

us_mailings_suite_link_return_code: Optional[str]

See USPS DPV

us_state_legislative_lower: Optional[str]

Lower legislative district for the US address

us_state_legislative_upper: Optional[str]

Upper legislative district for the US address

us_time_zone: Optional[str]

Time zone for the US address area

vacant: Optional[bool]

Indicates that the address is vacant according to the USPS (US address only)

errors: Optional[Errors]

Errors encountered during address verification.

city: Optional[List[str]]

Errors related to the city.

generic: Optional[List[str]]

Generic errors not tied to a specific field.

line1: Optional[List[str]]

Errors related to the first address line.

line2: Optional[List[str]]

Errors related to the second address line.

province_or_state: Optional[List[str]]

Errors related to the province or state.

firm_name: Optional[str]

The firm name of the address.

geocode_result: Optional[DataGeocodeResult]

If the geocode=true query parameter is supplied, the response will include a geocodeResult which follows the Geocoding schema. You can request this feature be enabled by emailing [email protected]. This includes our verification, batch verification, suggestions, and POST /completions endpoint. Note that you must supply country when geocoding to get the result successfully.

accuracy: float

A real number from 0.00 to 1.00 which represents an accuracy score

accuracy_type: Literal["rooftop", "point", "range_interpolation", 5 more]

A string representing the accuracy type

One of the following:
"rooftop"
"point"
"range_interpolation"
"nearest_rooftop_match"
"intersection"
"street_center"
"place"
"state"
location: DataGeocodeResultLocation

Object that contains lat, lng properties with number values

lat: float
lng: float
line2: Optional[str]

The second line of the address.

status: Optional[Status]

The verification status of an address.

One of the following:
"verified"
"corrected"
"failed"
zip_plus4: Optional[str]

The zip plus 4 code of the address.

message: str
status: Literal["success", "error"]
One of the following:
"success"
"error"

Verify

import os
from postgrid import PostGrid

client = PostGrid(
    address_verification_api_key=os.environ.get("POSTGRID_ADDRESS_VERIFICATION_API_KEY"),  # This is the default and can be omitted
)
response = client.address_verification.verify(
    address="1234 Elm St, Los Angeles, CA 90001, US",
)
print(response.data)
{
  "status": "success",
  "message": "Address verified successfully",
  "data": {
    "city": "Los Angeles",
    "country": "US",
    "line1": "1234 Elm St",
    "postalOrZip": "90001",
    "provinceOrState": "CA",
    "status": "verified",
    "errors": {}
  }
}
{
  "status": "success",
  "message": "Address verified successfully",
  "data": {
    "city": "Los Angeles",
    "country": "US",
    "line1": "1234 Elm St",
    "postalOrZip": "90001",
    "provinceOrState": "CA",
    "status": "verified",
    "errors": {}
  }
}
Returns Examples
{
  "status": "success",
  "message": "Address verified successfully",
  "data": {
    "city": "Los Angeles",
    "country": "US",
    "line1": "1234 Elm St",
    "postalOrZip": "90001",
    "provinceOrState": "CA",
    "status": "verified",
    "errors": {}
  }
}
{
  "status": "success",
  "message": "Address verified successfully",
  "data": {
    "city": "Los Angeles",
    "country": "US",
    "line1": "1234 Elm St",
    "postalOrZip": "90001",
    "provinceOrState": "CA",
    "status": "verified",
    "errors": {}
  }
}