Find Service Points

This article explains what Service Points are, commonly called Pick-Up, Drop-Off Services, (PUDO). It describes their benefits, shows how to make API calls for the two endpoints for PUDO Service Points that ShipEngine supports, and also explains how to search for service points using the two available endpoints offered by ShipEngine:

POST Call - POST /v1/service_points/list:
- There are three ways you can use this call
GET Call - GET /v1/service_points/{carrier_code}/{country_code}/{service_point_id}:
- There is one way to use this call

Display the information provided for these Service Points at checkout to allow your customers to select the most convenient location to collect or ship their parcel. This information includes details like Address/ Geological Location, Hours of Operation, Features, and ServicePoint ID.

Benefits of PUDO Service Points

With Service Points, customers can pick up or drop off packages at designated locations, rather than having them delivered to their home, office, or business address.

Service Points are designated locations where the recipient can collect your shipment at their convenience. These PUDO Service Points are typically established in convenient and accessible locations such as retail stores, convenience stores, gas stations, or other centralized spots.

Customer-centric ecommerce companies and logistics providers who commonly use Service Points as part of their delivery solutions hold several advantages that benefit both consumers and businesses:

Convenience: PUDO services provide flexibility to customers who may not be available at home during typical delivery hours. They can pick up or drop off their parcels at a time that best suits them.
Reduce Missed Deliveries: Since customers can collect their items at their own convenience, it reduces the chance of missed deliveries and the need for re-delivery attempts.
Cost-Efficiency: PUDO services can be more cost-effective for businesses since they can consolidate deliveries to a central location rather than making individual trips to specific addresses.
Reduced Environmental Impact: Centralized drop-off points can lead to more efficient routes, potentially reducing the carbon footprint of deliveries.
Expanded Delivery Options: PUDO service points can be particularly useful in areas where standard home delivery is challenging, like in rural or densely populated urban areas.

General Requirements

Use a carrier that provides PUDO services.
Make sure that the carrier's service supports Service Points. If not you’ll get an error message.
Check with that carrier about specifics: Do they permit PUDO use only for certain services? Does it require an advanced option? Learn how to make a call that lists advanced options for a carrier.
Know the service point details. For instance, when you select some service points, the carrier may require specific properties to appear in the API call.

POST Call: Find Service Point Locations

This section explains how to find Service Points (PUDO) locations. You will learn how to make a POST call to search for Service Points near a chosen address for your selected carriers and services.

Similar to the Quickstart: Create a Label guide, we need to know some basic information to get Service Points.

Requirements: Find Service Points

To find Service Points, you must include the following:

The carrier_id for any carriers you wish to retrieve Service Points for. Find your carrier_id using List Your Carriers.
One (but not more than one) of the following location identifier groups:

lat and long
... or ...
addressline_1, city_locality,state_province, postal_code, and country_code
... or ...
address_query

Service Points Properties Table

The following table lists the parameters required for this endpoint. For samples of a full request, see the Example Requests section below.

Property Name	Required	Type	Description
`address`		Object	Always provide the `country_code` and at least one other field (i.e., `city` and `country_code`). The more fields you enter, the more accurate your results will be.
`address_query`		String	Unstructured text to search for service points by. (i.e., 123 Any St, Austin, TX)
`carrier_id`	✔	String	Need at least one, can be multiple carriers.
`country_code`	✔	String	2 characters. Example: CA. A two-letter ISO 3166-1 country code
`lat`		Integer	The latitude of the point. Represented as signed degrees. Required if `long` is provided. Latitude & Longitude Formats
`long`		Integer	The longitude of the point. Represented as signed degrees. Required if `lat` is provided. Latitude & Longitude Formats
`max_results`	Optional	Number	The maximum number of service points to return. Default is 100
`providers`	✔	Array of Objects	An array of shipping service providers and service codes
`radius`	Optional	Number	Search radius in kilometers
`service_code`	Optional	String	For a single service code. For multiple service codes, separate each with a comma. The carrier's service must support Service Points.

POST Call - Example Requests

POST /v1/service_points/list

Below are 3 examples of different ways to POST calls in JSON. Each example includes the response you should see returned, plus how to understand and use their results. These examples to help you locate Service Points include:

Search by Lat, Long
Search by Address
Search by Address string

Example Request 1: Search Service Points with Latitude & Longitude

Click to see Example Request 1: Search Service Points with Latitude & Longitude

This example shows how to get a list of Service Points by providing longitude and latitude (lat & long), and filtering by a specific carrier and service. You can then use a Service_Point_ID to Print a Label for that shipping location. sends lat and long details along with carrier_id and service_code properties in the POST call.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
POST /v1/service_points/list HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "lat": "48.8724402",
  "long": "2.3120628",
  "providers": [
    {
      "carrier_id": "se-123",
      "service_code": [
        "ups_standard"
      ]
    }
  ],
  "radius": 500,
  "max_results": 25
}

Example Request 2: Search Service Points by Address

Click to see Example Request 2**: Search Service Points by Address

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
POST /v1/service_points/list HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "address_query": "177A Bleecker Street, New York",
  "providers": [
    {
      "carrier_id": "se-123456",
      "service_code": [
        "ups_standard"
      ]
    }
  ],
  "radius": 500,
  "max_results": 25
}

Example Request 3: Search Service Points by Address String

Click to see Example Request 3: Search Service Points by Address String

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
POST /v1/service_points/list HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "address": {
    "address_line1": "3800 North Lamar",
    "address_line2": "Suite 200",
    "address_line3": "string",
    "city_locality": "Austin",
    "state_province": "TX",
    "postal_code": "78652",
    "country_code": "US"
  },
  "providers": [
    {
      "carrier_id": "se-123456",
      "service_code": [
        "ups_standard"
      ]
    }
  ],
}

GET Call - Example Request

This GET call returns a carrier service point by using the service_point_id.

GET /v1/service_points/{carrier_code}/{country_code}/{service_point_id}

Click to see Example Request: GET Service Point By Service Point ID

This POST call will use a service_point_id to return address (object), hours_of_operation (object), features (String or Array of strings), and type ("pudo" or "locker") as they relate to the Service Point.

Property	Type	Required	Description
`carrier_code`	string	✔	Carrier code. non-empty Example: "chronopost"
`country_code`	string	✔	2 characters Example: FR A two-letter ISO 3166-1 country code
`service_point_id`	string	✔	Example: "614940"

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
GET /v1/service_points/{carrier_code}/{country_code}/{service_point_id}
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
  "service_point": {
    "carrier_code": "chronopost",
    "service_codes": [
      "string"
    ],
    "service_point_id": "614940",
    "company_name": "My fancy company name",
    "address_line1": "PLACE DU CANADA",
    "city_locality": "TRUN",
    "state_province": "TRUN",
    "postal_code": "61160",
    "country_code": "FR",
    "phone_number": "555-555-5555",
    "lat": 48.842608,
    "long": 0.032875,
    "hours_of_operation": {
      "monday": [
        {
          "open": "09:15",
          "close": "12:00"
        }
      ],
      "tuesday": [
        {
          "open": "09:15",
          "close": "12:00"
        }
      ],
      "wednesday": [
        {
          "open": "09:15",
          "close": "12:00"
        }
      ],
      "thursday": [
        {
          "open": "09:15",
          "close": "12:00"
        }
      ],
      "friday": [
        {
          "open": "09:15",
          "close": "12:00"
        }
      ],
      "saturday": [
        {
          "open": "09:15",
          "close": "12:00"
        }
      ],
      "sunday": [
        {
          "open": "09:15",
          "close": "12:00"
        }
      ]
    },
    "features": [
      "drop_off_point"
    ],
    "type": "pudo"
  }
}