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 or Drop Off locations near to a given postal code. You can use this operation, for example, to locate all USPS Post Offices near to a given postal code. New locations to drop off a PB Return can be found by using the PUDO_POINT facility type service with the carrier PBCS. An example is included at the bottom of this page.

If you use the PB 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

1. This operation currently supports searching for USPS facilities and partner drop off locations.

2. For best results, include the addressLines field in the address 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 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, PBCS.
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 name field that specifies the option and a value field that specifies option’s value. Both fields take Strings.
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
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. PUDO_POINT: Indicates a drop off location accepting PB Returns.
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
PACKAGELESS	Indicate TRUE to find drop off locations that support Packageless PB Returns.
QR_CODE	Indicate TRUE to only include the drop off locations that support scanning the QR_CODE used in Label Broker.

Facility Object (Response Only)

The carrierFacilitySuggestions array returns the facility object.

Name	Data Type	Description
address	Address Object	The address of the carrier facility.
carrierFacilityAttributes	Array[Object]	This array populates if: You did not specify a FACILITY_TYPE_SERVICE value in the request. A FACILITY_TYPE_SERVICE value applies. The array’s object contains a name-value pair (name field and value field) that specify the facility service. Both fields take Strings. 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: SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY
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 hours:minutes time format. The time is local to facility.
facilityTimings.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.

Sample Request for Label Broker Supported Post Offices

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 for Label Broker Supported Post Offices

{
    "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"
    },
    ...
    ]
}

Sample Request for a Drop Off Location

curl --location 'https://api.pitneybowes.com/shippingservices/v1/carrier-facility' \
 --header 'Authorization: Bearer <oauth_token>' \
 --header 'Content-Type: application/json' \
 --header 'Accept-Language: en-US' \
 --header 'X-PB-PartnerId: 159503200' \
 --data '{
       "carrier" : "PBCS",
       "address" : {
       "cityTown" : "WESTPORT",
          "stateProvince" : "CT",
          "postalCode" : "06880",
         "countryCode" : "US",
         "addressLines" : [ "110 Myrtle Avenue" ]
      },
       "carrierFacilityOptions" : [ {
          "name" : "FACILITY_TYPE_SERVICE",
          "value" : "PUDO_POINT"
    }, {
          "name" : "FACILITY_WITHIN_RADIUS",
          "value" : "3"
    }, {
          "name" : "NUMBER_OF_FACILITIES",
          "value" : "10"
    }, {
          "name" : "PACKAGELESS",
          "value" : "TRUE"
       },
      {
          "name" : "QR_CODE",
          "value" : "FALSE"
      }]
      }
     '

Sample Response for a Drop Off Location

 {
      "address": {
        "addressLines": [
          "110 Myrtle Avenue"
       ],
          "cityTown": "WESTPORT",
          "countryCode": "US",
          "postalCode": "06880",
          "stateProvince": "CT"
      },
      "carrier": "PBCS",
      "carrierFacilityOptions": [
     {
          "name": "FACILITY_TYPE_SERVICE",
          "value": "PUDO_POINT"
     },
     {
          "name": "FACILITY_WITHIN_RADIUS",
          "value": "3"
     },
     {
          "name": "NUMBER_OF_FACILITIES",
          "value": "10"
     },
     {
          "name": "PACKAGELESS",
          "value": "TRUE"
     },
     {
          "name": "QR_CODE",
          "value": "FALSE"
     }
       ],
      "carrierFacilitySuggestions": [
     {
       "address": {
          "addressLines": [
             "16 Railroad Pl",
              "",
              ""
            ],
           "cityTown": "Westport",
           "countryCode": "US",
           "phone": "203-212-9699",
           "postalCode": "06880",
           "stateProvince": "CT"
       },
        "carrierFacilityAttributes": [
       {
            "name": "LOCATION_ID",
            "value": "AB6152"
         },
         {
             "name": "LOCATION_NAME",
             "value": "Saugatuck Mail"
         },
         {
             "name": "LATITUDE",
             "value": "41.1192838"
         },
         {
             "name": "LONGITUDE",
            "value": "-73.3705073"
         },
         {
            "name": "PACKAGELESS",
            "value": "true"
         },
         {
            "name": "QRCODE",
            "value": "true"
         },
         {
            "name": "FACILITY_ID",
            "value": "AAH1"
         },
         {
            "name": "DISTANCE",
            "value": "1.9"
         }
      ],
        "facilityHours": [
         {
            "day": "MONDAY",
            "facilityTimings": [
               {
                  "closesAt": "18:00:00",
                  "opensAt": "6:00:00"
               }
            ]
         },
         {
            "day": "TUESDAY",
            "facilityTimings": [
               {
                  "closesAt": "18:00:00",
                  "opensAt": "6:00:00"
               }
            ]
         },
         {
              "day": "WEDNESDAY",
              "facilityTimings": [
               {
                   "closesAt": "18:00:00",
                   "opensAt": "6:00:00"
               }
            ]
         },
         {
              "day": "THURSDAY",
              "facilityTimings": [
                {
                    "closesAt": "18:00:00",
                    "opensAt": "6:00:00"
               }
            ]
         },
         {
              "day": "FRIDAY",
              "facilityTimings": [
              {
                    "closesAt": "18:00:00",
                    "opensAt": "6:00:00"
               }
            ]
         },
        {
              "day": "SATURDAY",
              "facilityTimings": [
                 {
                    "closesAt": "12:00:00",
                    "opensAt": "8:00:00"
                }
             ]
          }
        ],
       "  facilityParking": null
     }
  ]
}

Error Codes

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

 
 
 
 

• next
• previous |

© Copyright 2024 Pitney Bowes Inc. All rights reserved.