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 Valid values:
|
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 |
Accept-Language |
Language and country code. Default: |
X-PB-UnifiedErrorStructure |
Recommended. Set this to |
Request Elements¶
Name |
Data Type |
Description |
---|---|---|
address |
The address for which to retrieve suggestions. The following Address Object fields are required:
|
Response Elements¶
Name |
Data Type |
Description |
---|---|---|
address |
The original address. This might contain changes made for address validation. The Address Object’s |
|
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:
|
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¶
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
}
}'
{
"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¶
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
}
}'
{
"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.