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.

• 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.

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 support@postgrid.com. 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"
}