Aller au contenu
Address Validation iO

Cette documentation est disponible en anglais uniquement.

API

Validate an address

Check a postal address with POST /v1/addresses/validate and act on the decision, suggestions and issues it returns.

POST /v1/addresses/validate checks one address and tells you what to do with it. Use it in your checkout, in a customer account or anywhere a customer enters an address. Standalone address checks are not metered; they only count against your hourly limit. To check the address of a placed order, use Orders instead.

Request

Field Type Description
address object The address to check. Required.
context string Where the address comes from: checkout, account, other or test. Optional.
email string The buyer's email, for your checkout rules. Only allowed with context: "checkout". Never stored or logged.

The address object:

Field Description
countryCode ISO 3166-1 alpha-2 code, such as DE or US. Required.
address1 Street and house number.
address2 Apartment, suite, building.
city City or town.
zip Postal code.
province, provinceCode State or region, as a name or a code.
firstName, lastName, company, phone Optional. Sent along with the address.

Empty optional fields may be omitted or sent as null. Strings can be at most 255 characters.

About context:

  • checkout: the answer also contains rules, the checkout rules of your shop that the address (or the email) breaks.
  • account and other: a plain check. This is the default when you leave context out.
  • test: for an admin "test an address" screen. It always asks the provider (no cache), is never billed, and has its own hourly limit. A used-up test limit answers 429 rate_limited.

Example

curl https://api.address-validation.io/v1/addresses/validate \
  -H "Authorization: Bearer $AVIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "address1": "Unter den Linden 77",
      "city": "Berlin",
      "zip": "10118",
      "countryCode": "DE"
    },
    "context": "checkout"
  }'

Here the postal code was off by one digit. AVIO corrected it and asks the customer to confirm:

JSON
{
  "decision": "warn",
  "mode": "balanced",
  "addressHash": "5d0c3e9a7b41f2c86e1a9d07b3f5c2e48a6d1b90c7e3f5a2d4b6c8e0f1a3b5c7",
  "verdict": {
    "status": "corrected",
    "provider": "loqate",
    "granularity": "premise",
    "changes": [
      { "field": "zip", "from": "10118", "to": "10117", "kind": "minor" }
    ],
    "missing": [],
    "unverified": [],
    "suggestions": [
      {
        "address1": "Unter den Linden 77",
        "city": "Berlin",
        "zip": "10117",
        "countryCode": "DE"
      }
    ]
  },
  "issues": [],
  "rules": []
}

Read the result

decision

decision is the field to act on. It already applies the validation mode configured for the address's country.

decision What to do
valid Accept the address.
warn The address was corrected or is uncertain. Show the suggestion and let the customer confirm or edit.
invalid The address can't be delivered as entered. Ask the customer to fix it, offering verdict.suggestions if there are any.
skipped No answer, for example the country isn't covered, a provider failed or your hourly limit is used up. Let the customer continue.

The address check fails open: problems on our side answer skipped instead of an error, so a checkout never has to block on AVIO.

mode

The validation mode used for this check: strict, balanced or loose. Stricter modes turn more corrections and less precise matches into invalid.

verdict

verdict is the detail behind the decision:

Field Meaning
status The provider's view: deliverable, corrected, ambiguous, invalid, unsupported or error.
provider Which provider answered.
granularity How precisely the address was matched: subpremise (unit), premise (building), street, locality or none.
changes Each corrected field with field, from, to and kind (alias, format, minor, major or inferred).
missing Parts the customer left empty that are needed: house_number, street, subpremise, postbox_number, zip, city.
unverified Parts the customer entered that couldn't be confirmed (same values as missing).
suggestions Corrected addresses to offer, in the same shape as the input address. Can be empty.
suggestionsProvider The provider of the suggestions, when it differs from provider.
blocked poBox or parcelLocker when your delivery-point settings don't allow this kind of address. The decision is then invalid; ask for another address instead of offering suggestions.

Note: When suggestionsProvider (or, if absent, provider) is google, show Google's attribution ("Google Maps", or the Google Maps logo where you can) next to the suggestions. This is a license requirement.

issues

issues lists problems found in the address as entered, before any provider was asked: missing_house_number, empty_required_field, zip_in_address1, email_in_field, phone_in_field, url_in_field, po_box, po_box_blocked, parcel_locker, parcel_locker_without_number, parcel_locker_blocked and address_rule. Use them to show a precise hint next to the right field.

rules

Only with context: "checkout". Each entry is { "code", "field" }, one per checkout rule of your shop the input breaks, for example { "code": "house_number", "field": "address1" }. Codes: house_number, zip_format, too_long, po_box, parcel_locker_blocked, parcel_locker, email_invalid, email_disposable, address_rule. Fields: address1, address2, city, zip, province, email. An empty list means no rule is broken.

Address rules

If your shop has address rules, two more fields can appear:

  • addressRules: the rules that matched, each as { "id", "action", "field" }.
  • rewrite: the address after your replace rules. This is the address that was checked and that verdict describes. Decide yourself whether to write it back.

Both are absent when no rule matched.

addressHash

A hash of the normalized address. The same address gives the same hash, so you can use it to tell whether a customer changed the address since the last check.

Full reference

The full request and response schema is in the API reference.