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 Description
returnSuggestions

Required. To return suggested addresses, set this to true.

Valid values:

  • true
  • false

Request Headers

Name
Description
Authorization Required. OAuth token generated using the Generate an OAuth Token API.
Content-Type Required. The media type of the request entity. Set this to application/json.
Accept-Language Language and country code. Default: en-US
X-PB-UnifiedErrorStructure Recommended. Set this to true to use the standard error object if an error occurs.

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.

Sample Requests

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" \
-H "X-PB-UnifiedErrorStructure: true" \
-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" \
-H "X-PB-UnifiedErrorStructure: true" \
-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

Error codes specific to address validation are seven-digits long and start with 10. See the address-specific errors in 7-Digit Error Codes.

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