Skip to content
PostGrid PostGrid
Get started
API Reference
Intl Address Verification

Verify

intl_address_verification.verify(IntlAddressVerificationVerifyParams**kwargs) -> IntlAddressVerificationVerifyResponse
POST/v1/intl_addver/verifications

Verify and standardize an international address.

  • Supports both structured and freeform address inputs.
  • Specify includeDetails=true to get additional details as per the IntlDetails schema.
  • Uses 1 lookup.
ParametersExpand Collapse
country: str

The country code (ISO 3166-1 alpha-2 or alpha-3).

line1: str

The first line of the address (e.g., street address, building, etc.).

postal_or_zip: str

The postal or ZIP code.

province_or_state: str

The administrative area (e.g., state, province, region).

city: Optional[str]

The city, town, or locality of the address.

line2: Optional[str]

The second line of the address (e.g., apartment, suite, etc.).

line3: Optional[str]

The third line of the address (e.g., additional locality or delivery info).

line4: Optional[str]

The fourth line of the address (e.g., further address details).

geo_data: Optional[bool]
include_details: Optional[bool]
proper_case: Optional[bool]
ReturnsExpand Collapse
class IntlAddressVerificationVerifyResponse: …
data: Data

The result of a verified international address.

city: str

The city or locality.

country: str

The country code (ISO 3166-1 alpha-2).

line1: str

The first address line.

postal_or_zip: str

The postal or ZIP code.

province_or_state: str

The province or state.

country_name: Optional[str]

The full country name.

details: Optional[DataDetails]

Additional details about the verified address, such as premise, thoroughfare, and locality.

building: Optional[str]

The building name or number.

building_type: Optional[str]

The type of building (e.g., apartment, office).

city_name: Optional[str]

The full city name.

city_secondary: Optional[str]

Secondary city information.

city_type: Optional[str]

The type of city (e.g., city, town, village).

delivery_address: Optional[str]

The full delivery address.

dependent_locality: Optional[str]

The dependent locality (UK addresses).

double_dependent_locality: Optional[str]

The double dependent locality (UK addresses).

organization: Optional[str]

The organization or company name.

postal_or_zip_primary: Optional[str]

The primary part of the postal or ZIP code.

postal_or_zip_secondary: Optional[str]

The secondary part of the postal or ZIP code.

post_box: Optional[str]

The post box number.

premise: Optional[str]

The premise name or number.

premise_number: Optional[str]

The premise number.

premise_secondary: Optional[str]

Secondary premise information.

premise_type: Optional[str]

The type of premise (e.g., house, flat).

province_or_state_name: Optional[str]

The full name of the province or state.

province_or_state_type: Optional[str]

The type of province or state (e.g., province, state, region).

street: Optional[str]

The street name.

street_post_direction: Optional[str]

The directional suffix for the street (e.g., N, S, E, W).

street_pre_direction: Optional[str]

The directional prefix for the street (e.g., N, S, E, W).

street_type: Optional[str]

The type of street (e.g., St, Ave, Blvd).

sub_administrative_area: Optional[str]

The sub-administrative area.

sub_building: Optional[str]

The sub-building name or number (e.g., unit, suite).

sub_building_floor: Optional[str]

The floor of the sub-building.

sub_building_number: Optional[str]

The sub-building number.

sub_building_type: Optional[str]

The type of sub-building (e.g., floor, wing).

sub_street: Optional[str]

The sub-street name.

sub_street_post_direction: Optional[str]

The directional suffix for the sub-street.

sub_street_pre_direction: Optional[str]

The directional prefix for the sub-street.

sub_street_type: Optional[str]

The type of sub-street.

super_administrative_area: Optional[str]

The super-administrative area.

telephone: Optional[str]

The telephone number associated with the address.

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 or company name, if available.

formatted_address: Optional[str]

The formatted address string.

geo_data: Optional[DataGeoData]

Geocoding result for the verified address.

geo_accuracy: Optional[str]

The geocode accuracy.

latitude: Optional[str]

The latitude of the address.

longitude: Optional[str]

The longitude of the address.

line2: Optional[str]

The second address line.

line3: Optional[str]

The third address line, if available.

status: Optional[Status]

The verification status of an address.

One of the following:
"verified"
"corrected"
"failed"
summary: Optional[DataSummary]

A summary of the verification process and match levels.

context_identification_match_level: Optional[str]

Context identification match level.

lexicon_identification_match_level: Optional[str]

Lexicon identification match level.

match_score: Optional[float]

The match score (0-100).

message: Optional[str]

Additional message about the verification.

parsing_status: Optional[str]

The parsing status of the address.

post_code_status: Optional[str]

The status of the postal code.

post_processed_verification_match_level: Optional[str]

The match level after post-processing.

pre_processed_verification_match_level: Optional[str]

The match level before post-processing.

verification_status: Optional[str]

The overall verification status.

zip_plus4: Optional[str]

The ZIP+4 code (for US addresses).

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.intl_address_verification.verify(
    address={},
)
print(response.data)
{
  "status": "success",
  "message": "International address verified successfully.",
  "data": {
    "city": "Scarborough",
    "country": "CA",
    "details": {
      "premise": "31"
    },
    "formattedAddress": "31 Fl,scarborough On",
    "geoData": {
      "latitude": "43.761961",
      "longitude": "-79.245693",
      "geoAccuracy": "A2"
    },
    "line1": "31 Fl",
    "line2": "Scarborough On",
    "provinceOrState": "ON",
    "postalOrZip": "",
    "summary": {
      "verificationStatus": "partially_verified",
      "postProcessedVerificationMatchLevel": "city",
      "preProcessedVerificationMatchLevel": "city",
      "parsingStatus": "unable_to_parse",
      "lexiconIdentificationMatchLevel": "city",
      "contextIdentificationMatchLevel": "premise_or_building",
      "postCodeStatus": "postal_code_primary_empty",
      "matchScore": 100
    }
  }
}
{
  "status": "success",
  "message": "International address verified successfully.",
  "data": {
    "city": "Reilingen",
    "country": "DE",
    "details": {
      "building": "Reilingen Baden Wurtemberg",
      "premise": "43"
    },
    "formattedAddress": "Reilingen Baden Wurtemberg,hockenheimer Str. 43,68799 Reilingen",
    "geoData": {
      "latitude": "49.297010",
      "longitude": "8.571100",
      "geoAccuracy": "P4"
    },
    "line1": "Reilingen Baden Wurtemberg",
    "line2": "Hockenheimer Str. 43",
    "line3": "68799 Reilingen",
    "postalOrZip": "68799",
    "provinceOrState": "Baden-Württemberg",
    "summary": {
      "verificationStatus": "verified",
      "postProcessedVerificationMatchLevel": "premise_or_building",
      "preProcessedVerificationMatchLevel": "premise_or_building",
      "parsingStatus": "unable_to_parse",
      "lexiconIdentificationMatchLevel": "premise_or_building",
      "contextIdentificationMatchLevel": "premise_or_building",
      "postCodeStatus": "postal_code_primary_empty",
      "matchScore": 100
    }
  }
}
Returns Examples
{
  "status": "success",
  "message": "International address verified successfully.",
  "data": {
    "city": "Scarborough",
    "country": "CA",
    "details": {
      "premise": "31"
    },
    "formattedAddress": "31 Fl,scarborough On",
    "geoData": {
      "latitude": "43.761961",
      "longitude": "-79.245693",
      "geoAccuracy": "A2"
    },
    "line1": "31 Fl",
    "line2": "Scarborough On",
    "provinceOrState": "ON",
    "postalOrZip": "",
    "summary": {
      "verificationStatus": "partially_verified",
      "postProcessedVerificationMatchLevel": "city",
      "preProcessedVerificationMatchLevel": "city",
      "parsingStatus": "unable_to_parse",
      "lexiconIdentificationMatchLevel": "city",
      "contextIdentificationMatchLevel": "premise_or_building",
      "postCodeStatus": "postal_code_primary_empty",
      "matchScore": 100
    }
  }
}
{
  "status": "success",
  "message": "International address verified successfully.",
  "data": {
    "city": "Reilingen",
    "country": "DE",
    "details": {
      "building": "Reilingen Baden Wurtemberg",
      "premise": "43"
    },
    "formattedAddress": "Reilingen Baden Wurtemberg,hockenheimer Str. 43,68799 Reilingen",
    "geoData": {
      "latitude": "49.297010",
      "longitude": "8.571100",
      "geoAccuracy": "P4"
    },
    "line1": "Reilingen Baden Wurtemberg",
    "line2": "Hockenheimer Str. 43",
    "line3": "68799 Reilingen",
    "postalOrZip": "68799",
    "provinceOrState": "Baden-Württemberg",
    "summary": {
      "verificationStatus": "verified",
      "postProcessedVerificationMatchLevel": "premise_or_building",
      "preProcessedVerificationMatchLevel": "premise_or_building",
      "parsingStatus": "unable_to_parse",
      "lexiconIdentificationMatchLevel": "premise_or_building",
      "contextIdentificationMatchLevel": "premise_or_building",
      "postCodeStatus": "postal_code_primary_empty",
      "matchScore": 100
    }
  }
}