API Reference

Address Verification

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Batch Verification

address_verification.batch_verification(AddressVerificationBatchVerificationParams**kwargs) -> AddressVerificationBatchVerificationResponse

POST/v1/addver/verifications/batch

Verify a batch of US or Canadian addresses in a single request. Each address can be freeform or structured, matching the same input formats accepted by the single verification endpoint.

• Accepts up to 2,000 addresses per request.
• Uses 1 lookup per address (plus 1 more per address if geocoding).
• Requires a secret API key.
• Returns results in the same order as the input addresses.
• If an individual address fails, its result will contain an error field rather than a verifiedAddress.
• If you are not subscribed and the batch would exceed your remaining free lookups, the entire batch fails (nothing is verified). Size your batch to the number of lookups you have left.

ParametersExpand Collapse

addresses: Iterable[Address]

Array of addresses to verify. Each item can be a freeform string or structured address object.

One of the following:

class AddressStandardFreeformAddressInput: …

address: str

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

class AddressStandardStructuredAddressInput: …

address: AddressStandardStructuredAddressInputAddress

city: str

The city of the address.

country: Literal["ca", "us"]

The country of your address, one of ca or us.

One of the following:

"ca"

"us"

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.

line2: Optional[str]

The second line of the address.

recipient: Optional[str]

The optional firm/recipient name.

geocode: Optional[bool]

include_details: Optional[bool]

proper_case: Optional[bool]

ReturnsExpand Collapse

class AddressVerificationBatchVerificationResponse: …

data: Data

results: List[DataResult]

error: Optional[str]

An error message for this address. Present when verification failed.

verified_address: Optional[DataResultVerifiedAddress]

The verified address result. Present when verification succeeded.

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[DataResultVerifiedAddressDetails]

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_fips: Optional[str]

US Census FIPS code (US address only)

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_postnet_barcode: Optional[str]

PostNet barcode for the address (US address only)

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.

postal_or_zip: Optional[List[str]]

Errors related to the postal or ZIP code.

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[DataResultVerifiedAddressGeocodeResult]

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: DataResultVerifiedAddressGeocodeResultLocation

Object that contains lat, lng properties with number values

lat: float

lng: float

line2: Optional[str]

The second line of the address.

province_or_state_name: Optional[str]

The full name of the province or state.

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"

Batch Verification

Python

HTTP

TypeScript

Python

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.batch_verification(
    addresses=[{
        "address": "address"
    }],
)
print(response.data)

200 example

{
  "data": {
    "results": [
      {
        "error": "error",
        "verifiedAddress": {
          "city": "city",
          "country": "country",
          "line1": "line1",
          "postalOrZip": "postalOrZip",
          "provinceOrState": "provinceOrState",
          "countryName": "countryName",
          "details": {
            "boxID": "boxID",
            "county": "county",
            "countyNum": "countyNum",
            "deliveryInstallationAreaName": "deliveryInstallationAreaName",
            "deliveryInstallationQualifier": "deliveryInstallationQualifier",
            "deliveryInstallationType": "deliveryInstallationType",
            "extraInfo": "extraInfo",
            "postDirection": "postDirection",
            "preDirection": "preDirection",
            "residential": true,
            "ruralRouteNumber": "ruralRouteNumber",
            "ruralRouteType": "ruralRouteType",
            "streetDirection": "streetDirection",
            "streetName": "streetName",
            "streetNumber": "streetNumber",
            "streetType": "streetType",
            "suiteID": "suiteID",
            "suiteKey": "suiteKey",
            "usCensusBlockNumber": "usCensusBlockNumber",
            "usCensusCMSA": "usCensusCMSA",
            "usCensusFIPS": "usCensusFIPS",
            "usCensusMA": "usCensusMA",
            "usCensusMSA": "usCensusMSA",
            "usCensusPMSA": "usCensusPMSA",
            "usCensusTractNumber": "usCensusTractNumber",
            "usCongressionalDistrictNumber": "usCongressionalDistrictNumber",
            "usHasDaylightSavings": true,
            "usMailingCheckDigit": "usMailingCheckDigit",
            "usMailingsCarrierRoute": "usMailingsCarrierRoute",
            "usMailingsDefaultFlag": true,
            "usMailingsDeliveryPoint": "usMailingsDeliveryPoint",
            "usMailingsDpvConfirmationIndicator": "usMailingsDpvConfirmationIndicator",
            "usMailingsDpvCrmaIndicator": "usMailingsDpvCrmaIndicator",
            "usMailingsDpvFootnote1": "usMailingsDpvFootnote1",
            "usMailingsDpvFootnote2": "usMailingsDpvFootnote2",
            "usMailingsDpvFootnote3": "usMailingsDpvFootnote3",
            "usMailingsElotAscDesc": "usMailingsElotAscDesc",
            "usMailingsElotSequenceNumber": "usMailingsElotSequenceNumber",
            "usMailingsEWSFlag": "usMailingsEWSFlag",
            "usMailingsLACSFlag": "usMailingsLACSFlag",
            "usMailingsLACSReturnCode": "usMailingsLACSReturnCode",
            "usMailingsRecordTypeCode": "usMailingsRecordTypeCode",
            "usMailingsSuiteLinkReturnCode": "usMailingsSuiteLinkReturnCode",
            "usPostnetBarcode": "usPostnetBarcode",
            "usStateLegislativeLower": "usStateLegislativeLower",
            "usStateLegislativeUpper": "usStateLegislativeUpper",
            "usTimeZone": "usTimeZone",
            "vacant": true
          },
          "errors": {
            "city": [
              "string"
            ],
            "generic": [
              "string"
            ],
            "line1": [
              "string"
            ],
            "line2": [
              "string"
            ],
            "postalOrZip": [
              "string"
            ],
            "provinceOrState": [
              "string"
            ]
          },
          "firmName": "firmName",
          "geocodeResult": {
            "accuracy": 0,
            "accuracyType": "rooftop",
            "location": {
              "lat": 0,
              "lng": 0
            }
          },
          "line2": "line2",
          "provinceOrStateName": "provinceOrStateName",
          "status": "verified",
          "zipPlus4": "zipPlus4"
        }
      }
    ]
  },
  "message": "message",
  "status": "success"
}

Returns Examples

200 example

{
  "data": {
    "results": [
      {
        "error": "error",
        "verifiedAddress": {
          "city": "city",
          "country": "country",
          "line1": "line1",
          "postalOrZip": "postalOrZip",
          "provinceOrState": "provinceOrState",
          "countryName": "countryName",
          "details": {
            "boxID": "boxID",
            "county": "county",
            "countyNum": "countyNum",
            "deliveryInstallationAreaName": "deliveryInstallationAreaName",
            "deliveryInstallationQualifier": "deliveryInstallationQualifier",
            "deliveryInstallationType": "deliveryInstallationType",
            "extraInfo": "extraInfo",
            "postDirection": "postDirection",
            "preDirection": "preDirection",
            "residential": true,
            "ruralRouteNumber": "ruralRouteNumber",
            "ruralRouteType": "ruralRouteType",
            "streetDirection": "streetDirection",
            "streetName": "streetName",
            "streetNumber": "streetNumber",
            "streetType": "streetType",
            "suiteID": "suiteID",
            "suiteKey": "suiteKey",
            "usCensusBlockNumber": "usCensusBlockNumber",
            "usCensusCMSA": "usCensusCMSA",
            "usCensusFIPS": "usCensusFIPS",
            "usCensusMA": "usCensusMA",
            "usCensusMSA": "usCensusMSA",
            "usCensusPMSA": "usCensusPMSA",
            "usCensusTractNumber": "usCensusTractNumber",
            "usCongressionalDistrictNumber": "usCongressionalDistrictNumber",
            "usHasDaylightSavings": true,
            "usMailingCheckDigit": "usMailingCheckDigit",
            "usMailingsCarrierRoute": "usMailingsCarrierRoute",
            "usMailingsDefaultFlag": true,
            "usMailingsDeliveryPoint": "usMailingsDeliveryPoint",
            "usMailingsDpvConfirmationIndicator": "usMailingsDpvConfirmationIndicator",
            "usMailingsDpvCrmaIndicator": "usMailingsDpvCrmaIndicator",
            "usMailingsDpvFootnote1": "usMailingsDpvFootnote1",
            "usMailingsDpvFootnote2": "usMailingsDpvFootnote2",
            "usMailingsDpvFootnote3": "usMailingsDpvFootnote3",
            "usMailingsElotAscDesc": "usMailingsElotAscDesc",
            "usMailingsElotSequenceNumber": "usMailingsElotSequenceNumber",
            "usMailingsEWSFlag": "usMailingsEWSFlag",
            "usMailingsLACSFlag": "usMailingsLACSFlag",
            "usMailingsLACSReturnCode": "usMailingsLACSReturnCode",
            "usMailingsRecordTypeCode": "usMailingsRecordTypeCode",
            "usMailingsSuiteLinkReturnCode": "usMailingsSuiteLinkReturnCode",
            "usPostnetBarcode": "usPostnetBarcode",
            "usStateLegislativeLower": "usStateLegislativeLower",
            "usStateLegislativeUpper": "usStateLegislativeUpper",
            "usTimeZone": "usTimeZone",
            "vacant": true
          },
          "errors": {
            "city": [
              "string"
            ],
            "generic": [
              "string"
            ],
            "line1": [
              "string"
            ],
            "line2": [
              "string"
            ],
            "postalOrZip": [
              "string"
            ],
            "provinceOrState": [
              "string"
            ]
          },
          "firmName": "firmName",
          "geocodeResult": {
            "accuracy": 0,
            "accuracyType": "rooftop",
            "location": {
              "lat": 0,
              "lng": 0
            }
          },
          "line2": "line2",
          "provinceOrStateName": "provinceOrStateName",
          "status": "verified",
          "zipPlus4": "zipPlus4"
        }
      }
    ]
  },
  "message": "message",
  "status": "success"
}