Address Normalizer Integration Guide

The Address Normalizer API is a PayPal limited release REST API that you can use in conjunction with other publicly available external APIs.

Overview

Often, users provide address information that does not exactly match the postal services-supplied address information. This mismatch can result in delivery delays of packages to physical addresses.

To help reduce this risk, you can use the verify and normalize an address method to compare an address to a list of verified addresses and normalize it to conform to its closest match.

You can use the verify and normalize an address method to:

• Quickly convert a user-provided address into a normalized and verified address.
• Determine whether a user-provided address cannot be verified and normalized.
• Maintain address consistency across systems and data stores to ease the synchronization and linking of address information.

The verify and normalize an address method returns a mailability field, which indicates the degree of confidence that the package can be delivered. The higher the value, the higher the chance that the package can be delivered.

Integration steps

Set up your development environment

Before you can integrate Address Normalizer, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate Address Normalizer.

Verify and normalize an address

To compare a user-provided address to a list of verified addresses and normalize it to conform to its closest match, provide the address in the request:

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/location/address-verify \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <Access-Token>" \
4  -d '{
5  "address": {
6    "address_details": {
7      "street_number": "1",
8      "street_name": "York",
9      "street_type": "Street",
10      "sub_building": "Level 23"
11    },
12    "admin_area_2": "sydney",
13    "postal_code": "2000",
14    "country_code": "AU"
15  },
16  "matching_scope": "ALL"
17}'

A successful request returns:

• A mailability rating that indicates the degree of confidence that the package can be delivered
• The address_type field, which indicates that type of address for delivery
• A verified and normalized address

1{
2  "status": "CORRECTED",
3  "message": "address corrected according to postal address",
4  "mailability": "5",
5  "address": {
6    "address": {
7      "address_line_1": "L 23 1 YORK ST",
8      "postal_code": "2000",
9      "admin_area_2": "Sydney",
10      "admin_area_1": "NSW",
11      "country_code": "AU",
12      "address_details": {
13        "street_name": "York St",
14        "street_number": "1",
15        "sub_building": "L 23"
16      }
17    },
18    "formatted_address": ["L 23 1 YORK ST", "SYDNEY NSW 2000", "AUSTRALIA"],
19    "complete_address": "L 23 1 YORK ST,SYDNEY NSW 2000,AUSTRALIA",
20    "geo_code": {
21      "longitude": "151.20543",
22      "latitude": "-33.86371"
23    }
24  }
25}

The higher the mailability value, the higher the chance that the package can be delivered to the address:

The address_type field can have one of these values:

List verified addresses

During sign-up and check-out flows when you gather addresses from users, you can pass the user-provided partial address information to this operation, which lists potential, verified addresses that match the partial address. This operation increases the quality of stored addresses because the API verifies all address suggestions against known postal databases.

To list verified addresses that match a user-provided partial address:

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/location/address-suggest \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <Access-Token>" \
4  -d '{
5  "address": {
6    "admin_area_2": "sanjose ",
7    "postal_code": "95131",
8    "country_code": "US"
9  }
10}'

A successful request returns a list of verified addresses that match the partial address:

1{
2  "status": "COMPLETE_ADDRESS",
3  "message": "suggested address are complete",
4  "addresses": [{
5    "address": {
6      "address_line_1": "1500 Adolfo Dr",
7      "postal_code": "95131",
8      "admin_area_1": "CA",
9      "admin_area_2": "Sanjose",
10      "country_code": "US",
11      "address_details": {
12        "street_name": "Adolfo Dr",
13        "street_number": "1500"
14      }
15    },
16    "formatted_address": ["1500 Adolfo Dr", "San Jose CA 95131", "United States"],
17    "complete_address": "1500 Adolfo Dr,San Jose CA 95131,United States"
18  }, {
19    "address": {
20      "address_line_1": "1800 Anchorage Lndg",
21      "postal_code": "95131",
22      "admin_area_1": "CA",
23      "admin_area_2": "Sanjose",
24      "country_code": "US",
25      "address_details": {
26        "street_name": "Anchorage Lndg",
27        "street_number": "1800"
28      }
29    },
30    "formatted_address": ["1800 Anchorage Lndg", "San Jose CA 95131", "United States"],
31    "complete_address": "1800 Anchorage Lndg,San Jose CA 95131,United States"
32  }]
33}

Additional information

• Address Normalizer Limited Release API Reference