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.

Considerations

  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 URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/addresses/verify-suggest?returnSuggestions=true
Production: https://shipping-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. The following Address Object fields are required:

  • addressLines

  • postalCode

  • countryCode

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.

suggestions.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

suggestions.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": "John Smith",
        "residential": true
    }
}'
Sample Request
{
    "address": {
        "addressLines": [
            "27 Waterview Dr"
        ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484-4301",
        "countryCode": "US",
        "name": "John Smith",
        "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": "John Smith"
            }
        ]
    }
}

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 error codes returned by the Ecommerce APIs, please see Error Codes.