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¶

The suggested addresses are not validated. To validate a suggested address, use the Address Validation API.
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.
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
The API returns a maximum of 20 suggestions.
The suggestions are not sorted by best match.
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
Returned Address is Validated and Changed

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 10-Prefix Error Codes.

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.