Find Service Points

ShipEngine offers two methods to find service points and their associated details:

List service points: POST /v1/service_points/list
- Lists all available service points for the carrier with their service point ID and related details. This method relies on either the address or latitude and longitude as the reference point and allows you to refine your results by indicating a distance radius in kilometers.
Get service point by ID: GET /v1/service_points/{carrier_code}/{country_code}/{service_point_id}
- Returns the service point details of a specific service point. This method relies on adding the carrier code, country code, and service point ID as path parameters to the endpoint.

If you are new to using service points, review our Introduction to Service Points and Create PUDO Labels pages to learn more about using service points with ShpEngine.

Requirements

The service points endpoint is available only to accounts on an Advanced plan or higher.

Service Points Properties

Property	Required?	Type	Description
`address_query`	✔ *	String	Unstructured address text to search for service points. (EX: 123 Any St, Austin, TX)
`address`	✔ *	Object	When used, you must provide the `country_code` and at least one other address property (Ex: `city` and `country_code`). The more fields you enter, the more accurate your results will be.
`country_code`	✔	String	A required property in the `address` object. Use the 2-character ISO 3166-1 country code.
`providers`	✔	Array of Objects	The array of carriers and service codes to be included in the search for service points. This object includes the `carrier_id` and `service_code` properties.
`carrier_id`	✔	String	Property to include in the `providers` array. Requires at least one, but can include multiple carriers.
`service_code`	Optional	String	Can include a single service code or multiple. For multiple, separate each with a comma.
`lat`	✔ *	number `<double>`	The latitude of the service point, represented as signed degrees. Required if `long` is provided. See Latitude & Longitude Formats for lat/long format details.
`long`	✔ *	number `<double>`	The longitude of the service point, represented as signed degrees. Required if `lat` is provided. See Latitude & Longitude Formats for lat/long format details.
`radius`	Optional	Number	Search radius in kilometers.
`max_results`	Optional	Number	The maximum number of service points to list in the response. Default is 100.
`shipment`	Optional	object	Shipment information to use for service point selection. Includes the `total_weight` object and `packages` array.
`total_weight`		object	The total weight of the shipment. Requires the `value` property (number) and `unit` property (ennumerated string: `pound` `ounce` `gram` `kilogram`).
`packages`		array	An array of package dimensions. Includes the `dimensions` object, which requires the following properties: `unit` (ennumerated string: `inch` `centimeter`), `length` (number), `width` (number), `height` (number)

* Whether certain properties will be required in your request body will depend on which option you use to find service points. Review the List Service Points options and examples in the next section.

List Service Points

You have three options for finding service points using the POST /v1/service_points/list method.

Find by latitude and longitude
Find by address
Find by address string

You can filter the results provided in the response by including the following optional properties in your request:

service_code
radius
max_results

Additionally, if you include service codes in your request, the response will indicate which service_code relates to which service point.

Requirements

Every request must include the providers object with at least the carrier_id (list your carriers to find your carrier IDs).

In addition, the following properties are required based on the option you are using the find service points:

Find by latitude and longitude: requires both lat and long properties.
Find by address: requires country_code and at least one of the following - addressline_1, city_locality,state_province, postal_code (the more properties you include, the more accurate your results).
Find by address string: requires the address_query property.

Example Request: Find by Latitude & Longitude

This example shows how to get a list of service points for a specific carrier and service by providing longitude and latitude values. The request further specifies a radius of 50 km with a maximum of 25 results.

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": 50,
  "max_results": 25
}

Example Request: Find by Address

This example shows how to get a list of service points for a specific carrier and service by providing an address object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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",
    "city_locality": "Austin",
    "state_province": "TX",
    "postal_code": "78652",
    "country_code": "US"
  },
  "providers": [
    {
      "carrier_id": "se-123456",
      "service_code": [
        "ups_standard"
      ]
    }
  ],
}

Example Request: Find by Address String

This example shows how to get a list of service points for a specific carrier and service by providing an address_query string. The request further specifies a radius of 50 km with a maximum of 25 results.

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": 50,
  "max_results": 25
}

List Service Points Response

The list service points response will include a service_points array with multiple properties containing various details about each service point it includes. You can pass these properties through to your own applications to provide your customers with service point options in their checkout. You can also use the service_point_id value in the related PUDO field when creating a PUDO label.

This sample response includes all potential fields that would appear in the response, with sample data.

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
{
  "lat": 48.842608,
  "long": 0.032875,
  "service_points": [
    {
     "carrier_code": "dhl_express",
     "service_codes": ["chronoclassic"],
     "service_point_id": "614940",
     "company_name": "My fancy company name",
     "address_line1": "PLACE DU CANADA",
     "city_locality": "TRUN",
     "state_province": "TRUN",
     "postal_code": "78756-3717",
     "country_code": "CA",
     "phone_number": "555-555-5555",
     "lat": 48.842608,
     "long": 0.032875,
     "distance_in_meters": 728.9959308847579,
     "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"
    }
  ],
  "errors": []
}

The available features values are drop_off_point, pick_up_point, print_services, after_hours_locker, and after_hours_dropbox. The available type values are pudo and locker.

If an error occurs, the errors array will contain the details you need to troubleshoot the issue and change your request body to try again.

error_source
error_type
error_code
message
carrier_id
carrier_code
field_name

Please see the response section of the List Service Points method in our full API reference for the list of potential values for each property.

Get Service Point by ID

If you already know the ID of the service point you wish to use or get details for, you can use the GET method with the service points endpoint.

The response will return the service point location address details, hours_of_operation (object), features (array), and type (ennumerated string).

Requirements

This GET method requires adding the following path parameters to the endpoint:

carrier_code
country_code
service_point_id

Example Request & Response

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

1
2
3
4
GET /v1/service_points/{chronopost}/{FR}/{614940} HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

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
{
  "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"
  }
}