Find Carrier Facilities¶
HTTP Request¶
POST /v1/carrier-facility
Summary¶
This operation locates Post Offices and other facilities for a given carrier. You can use this operation, for example, to locate all USPS Post Offices near to a given postal code.
If you use the PB Standard Returns API and if you use the option to print a QR code, use this API to locate facilities where the buyer can print the label from the QR code.
Considerations¶
This operation currently supports searching for USPS facilities.
For best results, include the
addressLines
field in theaddress
object.
Request URLs¶
Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/carrier-facility
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/carrier-facility
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: |
Request / Response Elements¶
Name |
Data Type |
Description |
---|---|---|
address |
Required. The address of the buyer who is returning the parcel. The address object requires the For best results, also include the |
|
carrier |
String |
Required. The carrier. Valid value: |
carrierFacilityOptions |
Array[Object] |
Filters the types of facilities returned. Each object in the array is a name-value pair that specifies a carrier facility option. Each object contains a |
carrierFacilitySuggestions |
Array[Facility Object] |
RESPONSE ONLY. Carrier facilities. Each object in the array is a different facility. |
Carrier Facility Options¶
The carrierFacilityOptions
array takes the options described here.
Name |
Description |
---|---|
|
The type of facility to return. By default, the API returns type Possible value: |
|
Specifies a service the facility must offer. The API returns facilities that offer the service. Possible value:
|
|
The distance from the buyer in miles. Default value: |
|
The number of facilities to return. To return only the closest facility, set this to Default value: |
Facility Object (Response Only)¶
The carrierFacilitySuggestions
array returns the facility object.
Name |
Data Type |
Description |
---|---|---|
address |
The address of the carrier facility. |
|
carrierFacilityAttributes |
Array[Object] |
This array populates if:
The array’s object contains a name-value pair ( Note If you specified a FACILITY_TYPE_SERVICE value in the request, this array does not populate. |
facilityHours |
Array[Facility Hours Object] |
The days and hours of operation. Each object in the array defines the hours for a day of the week. |
Facility Hours Object (Response Only)¶
The carrierFacilitySuggestions.facilityHours
array returns the facility hours object.
Name |
Data Type |
Description |
---|---|---|
day |
String |
The day of the week. Possible values: |
facilityTimings |
Array[Object] |
The hours of operation for the specified day. |
facilityTimings.opensAt |
String |
The time the facility opens, specified using a 24-hour clock and the |
facilityTimings.closesAt |
String |
The time the facility closes, specified using a 24-hour clock and the |
facilityParking |
String |
The type of parking available at the facility. |
Sample Request¶
curl -X POST ".../v1/carrier-facility" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "Accept-Language: en-US" \
-d '
{
"address": {
"addressLines": [
"6525 Greenway Dr"
],
"cityTown": "Roanoke",
"stateProvince": "VA",
"countryCode": "US"
},
"carrier": "USPS",
"carrierFacilityOptions": [ {
"name": "FACILITY_TYPE_SERVICE",
"value": "LABEL_BROKER_RETAIL"
},{
"name": "FACILITY_TYPE",
"value": "POST_OFFICE"
},{
"name": "FACILITY_WITHIN_RADIUS",
"value": "10"
},{
"name": "NUMBER_OF_FACILITIES",
"value": "5"
} ]
}'
Sample Response¶
{
"address": {
"addressLines": [
"6525 Greenway Dr"
],
"cityTown": "Roanoke",
"countryCode": "US",
"stateProvince": "VA"
},
"carrier": "USPS",
"carrierFacilityOptions": [ {
"name": "FACILITY_TYPE_SERVICE",
"value": "LABEL_BROKER_RETAIL"
},{
"name": "FACILITY_TYPE",
"value": "POST_OFFICE"
},{
"name": "FACILITY_WITHIN_RADIUS",
"value": "10"
},{
"name": "NUMBER_OF_FACILITIES",
"value": "5"
} ],
"carrierFacilitySuggestions": [ {
"address": {
"addressLines": [
"6621 WILLIAMSON RD"
],
"cityTown": "ROANOKE",
"postalCode": "24019",
"stateProvince": "VA"
},
"carrierFacilityAttributes": [],
"facilityHours": [ {
"day": "MONDAY",
"facilityTimings": [ {
"closesAt": "16:00:00",
"opensAt": "08:00:00"
} ]
},{
"day": "TUESDAY",
"facilityTimings": [ {
"closesAt": "16:00:00",
"opensAt": "08:00:00"
} ]
},{
"day": "WEDNESDAY",
"facilityTimings": [ {
"closesAt": "16:00:00",
"opensAt": "08:00:00"
} ]
},{
"day": "THURSDAY",
"facilityTimings": [ {
"closesAt": "16:00:00",
"opensAt": "08:00:00"
} ]
},{
"day": "FRIDAY",
"facilityTimings": [ {
"closesAt": "16:00:00",
"opensAt": "08:00:00"
} ]
},{
"day": "SATURDAY",
"facilityTimings": [ {
"closesAt": "12:00:00",
"opensAt": "09:00:00"
} ]
} ],
"facilityParking": "LOT"
},
...
]
}
Error Codes¶
For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.