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.

Things to Consider

  1. This operation currently supports searching for USPS facilities.
  2. For best results, include the addressLines field in the address object.

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/carrier-facility
Production: https://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 application/json.
Accept-Language Language and country code. Default: en-US

Request / Response Elements

Name Data Type Description
address Address Object

Required. The address of the buyer who is returning the parcel.

The address object requires the countryCode field and either the postalCode field or both the cityTown and stateProvince fields.

For best results, also include the addressLines field.

carrier String Required. The carrier. Valid value: USPS
carrierFacilityOptions Array[] Filters the types of facilities returned. Each object specifies a carrier facility option.
    name String The name of the carrier facility option.
    value String The value of the carrier facility option.
carrierFacilitySuggestions Array[Object] RESPONSE ONLY. Carrier facilities. Each object in the array is a different facility.
    address Address Object The address of the carrier facility.
    carrierFacilityAttributes Array[Object]

If you specify a FACILITY_TYPE_SERVICE value in the request, this array does not populate.

If you do not specify a FACILITY_TYPE_SERVICE value in the request, this array displays the FACILITY_TYPE_SERVICE value, if applicable.

          name String The name of the option.
          value String The option’s value.
    facilityHours Array[Object] The days and hours of operation. Each object in the array defines the hours for a day of the week.
          day String The day of the week. Possible values: SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY
          facilityTimings Array[Object] The hours of operation for the specified day.
                  opensAt String The time the facility opens, specified using a 24-hour clock and the hours:minutes time format. The time is local to facility.
                  closesAt String The time the facility closes, specified using a 24-hour clock and the hours:minutes time format. The time is local to facility.
    facilityParking String The type of parking available at the facility.

Carrier Facility Options

The carrierFacilityOptions array in the Find Carrier Facilities request can take the options described here.

Name Description
FACILITY_TYPE

The type of facility to return. By default, the API returns type POST_OFFICE.

Possible value: POST_OFFICE

FACILITY_TYPE_SERVICE

Specifies a service the facility must offer. The API returns facilities that offer the service.

Possible value:

  • LABEL_BROKER_RETAIL: Indicates the facility allows retail customers to print labels from QR codes.
FACILITY_WITHIN_RADIUS

The distance from the buyer in miles.

Default value: 5

NUMBER_OF_FACILITIES

The number of facilities to return. To return only the closest facility, set this to 1.

Default value: 5
Maximum value: 200

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 PB Shipping APIs error codes, please see Error Codes.