Suggest Addresses

HTTP Request

POST /v1/addresses/verify-suggest?returnSuggestions=true

Summary

This operation returns suggested addresses. Use this if the Address Validation API call has returned an error.

Things to Consider

  1. The suggested addresses are not validated. To validate a suggested address, use the Address Validation API.

  2. Some suggestions might not be valid delivery points.

    This is especially true for range suggestions. For example, if the suggested valid range for a street is 1-100, the Suggest Addresses API call will consider all numbers in the range to be valid, even if the only valid delivery points are numbers 12, 24, and 36.

  3. For a given request, the API returns suggestions for one part of the address, as specified in the suggestions.suggestionType field.

    The suggestions will be for one of the following parts of the address:

    • Primary number range (e.g., street number, PO Box number)
    • Secondary number range (e.g., suite number, apartment number)
    • Street Name
    • City Name
    • Company Name
    • Puerto Rican Urbanization
  4. The API returns a maximum of 20 suggestions.

  5. The suggestions are not sorted by best match.

  6. Some requests might return no suggestions. If there are no suggestions, the suggestions object is not returned.

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/addresses/verify-suggest?returnSuggestions=true
Production: https://api.pitneybowes.com/shippingservices/v1/addresses/verify-suggest?returnSuggestions=true

Query Parameter

Name Data Type Description
returnSuggestions Boolean Required. To return suggested addresses, set this to true.

Request Headers

Name Data Type Description
Authorization String Required. OAuth token generated using the Generate an OAuth Token API.
Content-Type String Required. The media type of the request entity. Set this to application/json.
Accept-Language String Language and country code. Default: en-US

Request Elements

Name Data Type Description
address address object The address for which to retrieve suggestions.

Response Elements

Name Data Type Description
address address object The original address. This might contain changes made for address validation. The address object’s status field indicates if changes have been made.
suggestions Object Suggested changes for a specific part of the address. The suggested changes are not validated. To validate a suggested change, use the Address Validation API.
        suggestionType String

The part of the address that is changed in the accompanying suggestions. Possible values are:

  • street
  • streetPrimaryRange (e.g., street number, PO Box number)
  • secondaryRange (e.g., suite number, apartment number)
  • poBoxPrimaryRange
  • ruralRouteUnitRange
  • highwayContractUnitRange
  • city
  • company
  • puertoricanUrbanization
        address Array[address object] The suggestions. Each object in the array provides a suggested change to the returned address.

Examples

This section provides the following examples:

Returned Address is Validated and Not Changed

Sample Request

curl -X POST .../v1/addresses/verify-suggest?returnSuggestions=true \
–H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-d '
{
    "address": {
        "addressLines": [
            "3 1st Ave NW"
        ],
        "cityTown": "Litz",
        "stateProvince": "FL",
        "postalCode": "33549",
        "countryCode": "US",
        "name": "Jane Wilson",
        "residential": true
    }
}'

Sample Response

{
    "address": {
        "addressLines": [
            "3 1st Ave NW"
        ],
        "cityTown": "Litz",
        "stateProvince": "FL",
        "postalCode": "33549",
        "countryCode": "US",
        "name": "Jane Wilson",
        "residential": true,
        "status": "VALIDATED_AND_NOT_CHANGED"
    },
    "suggestions": {
        "suggestionType": "street",
        "address": [ {
            "addressLines": [
                "3 1ST AVE NE"
            ],
            "cityTown": "Litz",
            "stateProvince": "FL",
            "postalCode": "33549",
            "name": "Jane Wilson"
        },
        {
            "addressLines": [
                "3 1ST AVE SE"
            ],
            "cityTown": "Litz",
            "stateProvince": "FL",
            "postalCode": "33549",
            "name": "Jane Wilson"
        },
        ...
        ]
    }
}

Returned Address is Validated and Changed

Sample Request

curl -X POST .../v1/addresses/verify-suggest?returnSuggestions=true \
–H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-d '
{
    "address": {
        "addressLines": [
            "27 Watervw Dr"
            "",
            ""
        ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484",
        "countryCode": "US",
        "name": "Jon Miller",
        "residential": true
     ],
    }
}'

Sample Response

{
    "address": {
        "addressLines": [
            "27 Waterview Dr"
        ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484-4301",
        "countryCode": "US",
        "name": "Jon Miller",
        "residential": false,
        "deliveryPoint": "27",
        "carrierRoute": "C010",
        "status": "VALIDATED_CHANGED"
    },
    "suggestions": {
        "suggestionType": "company",
        "address": [
            {
                "addressLines": [
                    "27 Waterview Dr"
                ],
                "cityTown": "Shelton",
                "stateProvince": "CT",
                "postalCode": "06484-4301",
                "company": "PITNEY BOWES CREDIT CORP",
                "name": "Jon Miller"
            }
        ]
    }
}

Error Codes

For a list of all PB Shipping APIs error codes, please see Error Codes.

The following codes are specific to address validation.

Error Code Message  
1000505 Country Code must be 2 letters.  
1010990 Invalid or missing value for countryCode  
1012003 Company field cannot exceed ___ characters  
1012010 email field cannot exceed ___ characters  
1012012 Invalid/missing cityTown  
1012013 CityTown field cannot exceed ___ characters  
1012014 Invalid/missing stateProvince  
1012015 Invalid stateProvince field value. stateProvince field length has to be ___ characters  
1012016 Invalid/missing postalCode  
1012020 Only 3 address delivery lines are allowed  
1012021 Invalid/missing addressDeliveryLine1  
1012022 AddressLines field cannot exceed 79 characters SOLUTION
1012038 Either companyName or name fields are mandatory  
1012049 Provide at least one addressLine  
1019000 Invalid address provided SOLUTION
1019002 Invalid or missing value for countryCode.  
1019003 Either Invalid or missing street or stateProvince or postalcode.