Suggest Addresses

address_verification.suggest_addresses() -> AddressVerificationSuggestAddressesResponse

POST/v1/addver/suggestions

Returns up to 3 verified address suggestions for a given input address.

Useful as a fallback when POST /verifications returns a failed status — suggestions represent the closest matches found and may help the user identify the correct address.

Accepts the same freeform or structured input formats as POST /verifications.

Uses 1 lookup per call (plus 1 more if geocoding).

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 AddressVerificationSuggestAddressesResponse: …

data: List[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_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[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 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: DataGeocodeResultLocation

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"

Suggest Addresses

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.suggest_addresses(
    address="1234 Elm St, Los Angeles, CA 90001, US",
)
print(response.data)

{
  "status": "success",
  "message": "Addresses suggested successfully",
  "data": [
    {
      "city": "Los Angeles",
      "country": "US",
      "line1": "1234 Elm St",
      "postalOrZip": "90001",
      "provinceOrState": "CA",
      "status": "verified",
      "errors": {}
    }
  ]
}

{
  "status": "success",
  "message": "Addresses suggested successfully",
  "data": [
    {
      "city": "Los Angeles",
      "country": "US",
      "line1": "1234 Elm St",
      "postalOrZip": "90001",
      "provinceOrState": "CA",
      "status": "verified",
      "errors": {}
    }
  ]
}

Returns Examples

{
  "status": "success",
  "message": "Addresses suggested successfully",
  "data": [
    {
      "city": "Los Angeles",
      "country": "US",
      "line1": "1234 Elm St",
      "postalOrZip": "90001",
      "provinceOrState": "CA",
      "status": "verified",
      "errors": {}
    }
  ]
}

{
  "status": "success",
  "message": "Addresses suggested successfully",
  "data": [
    {
      "city": "Los Angeles",
      "country": "US",
      "line1": "1234 Elm St",
      "postalOrZip": "90001",
      "provinceOrState": "CA",
      "status": "verified",
      "errors": {}
    }
  ]
}