shipengine-logo

Find Pick-Up/Drop-Off (PUDO) Locations

This tutorial explains how to find Pick-Up and Drop-Off (PUDO) locations, or what we will refer to as Service Points. You will learn how to make a POST call to search for Service Points near a chosen address for your selected carriers and services.

Display these Service Points at checkout so your customers may choose the most convenient location from where they can collect or ship their parcel.

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

REQUIREMENTS

To get Service Points, you must include the following:

  1. The carrier_id for any carriers you wish to retrieve Service Points for. Find your carrier_id using List Your Carriers.
  2. 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

Request Body

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

Property NameRequiredTypeDescription
carrier_id✔StringNeed at least one, can be multiple carriers.
service_pointOptionalObjectSee Example Request 4.
service_codeOptionalStringFor a single service code. For multiple service codes, separate each with a comma.
radiusOptionalNumberSearch radius in kilometers
max_resultsOptionalNumberThe maximum number of service points to return. Default is 100
latIntegerThe latitude of the point. Represented as signed degrees. Required if long is provided. Latitude & Longitude Formats
longIntegerThe longitude of the point. Represented as signed degrees. Required if lat is provided. Latitude & Longitude Formats
address_queryStringUnstructured text to search for service points by. (i.e., 123 Any St, Austin, TX)
addressString.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.
country_codeString2 characters. Example: CA. A two-letter ISO 3166-1 country code

Example Requests

POST /v1/service_points/list

Below are four 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:

  1. Search by Lat, Long
  2. Search by Address
  3. Search by Address string
  4. Search by Service Point ID (if you know the PUDO location's service_point_ID and want information such as hours of operation, etc.)

Example Request 1: Search Service Points with Latitude & Longitude

Click to see Example Request 1: Details

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_acccess_points"
      ]
    }
  ],
  "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_access_points"
      ]
    }
  ],
  "radius": 500,
  "max_results": 25
}

Example Request 3: Search Service Points by Address String

Click to see Example Request 3: Details
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_access_points"
      ]
    }
  ],
}

Example Request 4: Search Service Points by Service Point ID

Click to see Example Request 4: Details

This POST call will return address (object), hours_of_operation (object), and features (String or Array of strings) as they relate to the Service Point.

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
73
74
75
76
77
78
GET /v1/service_points/ups/US/614940 HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "service_point": {
    "carrier_code": "ups",
    "service_codes": [
      "ups_access_points"
    ],
    "service_point_id": "614940",
    "address": {
      "phone_number": "555-555-5555",
      "company_name": "My fancy company name",
      "description": "This is a description of the service point",
      "geo": {
        "lat": 48.842608,
        "long": 0.032875
      },
      "name": "Nigel Winterlake",
      "address_line1": "3800 North Lamar",
      "address_line2": "Suite 200",
      "address_line3": "string",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78652",
      "country_code": "US"
    },
    "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"
    ]
  }
}