Pickup/Drop-Off Locations

Our API allows you to find nearby pickup or drop-off (PUDO) locations for carriers based on the location and distance.

Overview

These requests allow you to get pickup and drop-off locations from carriers through a proximity-based search with a single HTTPS request and is typically used during checkout and the returns process to provide location options.

You can retrieve location information through these APIs using a unique identifier and allow customers to choose a convenient location before a shipping label is generated.

Find Pickup/Drop-Off Locations

You can retrieve the pickup and drop-off locations for a carrier using the v4/track/place-info/lookup endpoint.

Lookup places

post

Lookup drop-off/pick-up locations for a courier, by location & distance.

Authorizations

OAuth2 AuthenticationHeaderToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

accountinteger[]Optional

orderingstringOptional

Which field to use when ordering the results.

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Place info lookup request.

Either 'location' or 'external_reference' must be provided (mutually non-exclusive).

accountintegerRequired

ID of account for this lookup

locationany ofOptional

Geographical location to search for places

Default: null

or

nullOptional

external_referenceany ofOptionalDefault: null

stringOptional

or

nullOptional

country_iso3stringRequired

ISO 3166-1 alpha-3 code of country

Pattern: ^\w{3}$

Responses

200Success

application/json

Place info response item augmented with distance from query point.

raw_place_typestringOptional

distancenumber · nullableRead-onlyRequired

Distance to the place

courierstring · max: 255Required

country_iso3string · max: 255Required

ISO 3166-1 alpha-3 code of the country

place_typeall ofOptional

Type of this place

• default - Default (first party)
• self_service - Self-Service / Locker
• partner_location - Partner Location
• store - Store
• other - Other (e.g. hub)

string · enumOptional

• default - Default (first party)
• self_service - Self-Service / Locker
• partner_location - Partner Location
• store - Store
• other - Other (e.g. hub)

Possible values:

namestring · max: 255Required

Name of this place

phone_numberstring · max: 255Optional

websitestring · uri · max: 200Optional

criteriastring[]Optional

Search Criteria that this place matches

raw_servicesstring[]Optional

Raw (carrier-provided) services provided at this place

has_detailsbooleanOptional

Whether this place info includes place details

is_in_servicebooleanOptional

Whether this place is in service (open)

external_referencestring · max: 255Optional

External (3rd party) reference of this place, e.g. unique location ID

external_idstring · uuidOptional

parcelLab generated unique ID for this place

additional_infoobjectOptional

Additional information about this place

400Error

application/json

403Error

application/json

post

/v4/track/place-info/lookup/

HTTPcURLJavaScriptPython

POST /v4/track/place-info/lookup/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 548

{
  "account": 1,
  "location": {
    "type": "Point",
    "latitude": 1,
    "longitude": 1,
    "postal_code": "text",
    "region_code": "text",
    "city": "text",
    "country_iso3": "text"
  },
  "external_reference": "text",
  "lookups": [
    {
      "courier": "text",
      "service_level": "text",
      "criteria": [
        "dropoff_location"
      ],
      "max_distance": 20,
      "unit": "km",
      "limit": 10
    }
  ],
  "country_iso3": "text",
  "location_address": {
    "first_name": "text",
    "last_name": "text",
    "company_name": "text",
    "address_line": "text",
    "address_line_extra": "text",
    "postal_code": "text",
    "city": "text",
    "country_iso3": "text",
    "region_code": "text",
    "phone": "text"
  }
}

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

[
  {
    "location_address": {
      "first_name": "text",
      "last_name": "text",
      "company_name": "text",
      "address_line": "text",
      "address_line_extra": "text",
      "postal_code": "text",
      "city": "text",
      "country_iso3": "text",
      "region_code": "text",
      "phone": "text"
    },
    "location": {
      "type": "Point",
      "latitude": 1,
      "longitude": 1,
      "postal_code": "text",
      "region_code": "text",
      "city": "text",
      "country_iso3": "text"
    },
    "opening_hours": [
      {
        "day": "mon",
        "open": "01:21:11",
        "close": "01:21:11"
      }
    ],
    "raw_place_type": "text",
    "distance": null,
    "courier": "text",
    "country_iso3": "text",
    "place_type": "default",
    "name": "text",
    "phone_number": "text",
    "website": "https://example.com",
    "criteria": [
      "text"
    ],
    "services": [
      "drop_box"
    ],
    "raw_services": [
      "text"
    ],
    "has_details": true,
    "is_in_service": true,
    "external_reference": "text",
    "external_id": "123e4567-e89b-12d3-a456-426614174000",
    "additional_info": {}
  }
]

Get Pickup/Drop-Off Location Details

You can retrieve the details of pickup and drop-off locations for a carrier using the v4/track/place-info/{external_id} endpoint.

Retrieve Place Info

get

Lookup drop-off/pick-up locations for a courier, by location & distance.

Authorizations

OAuth2 AuthenticationHeaderToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

external_idstring · uuidRequired

parcelLab generated unique ID for this place

Responses

200Success

application/json

Public representation of a pickup/drop-off place with geodata.

raw_place_typestringOptional

courierstring · max: 255Required

country_iso3string · max: 255Required

ISO 3166-1 alpha-3 code of the country

place_typeall ofOptional

Type of this place

• default - Default (first party)
• self_service - Self-Service / Locker
• partner_location - Partner Location
• store - Store
• other - Other (e.g. hub)

string · enumOptional

• default - Default (first party)
• self_service - Self-Service / Locker
• partner_location - Partner Location
• store - Store
• other - Other (e.g. hub)

Possible values:

namestring · max: 255Required

Name of this place

phone_numberstring · max: 255Optional

websitestring · uri · max: 200Optional

criteriastring[]Optional

Search Criteria that this place matches

raw_servicesstring[]Optional

Raw (carrier-provided) services provided at this place

has_detailsbooleanOptional

Whether this place info includes place details

is_in_servicebooleanOptional

Whether this place is in service (open)

external_referencestring · max: 255Required

External (3rd party) reference of this place, e.g. unique location ID

external_idstring · uuidOptional

parcelLab generated unique ID for this place

additional_infoobjectOptional

Additional information about this place

accountintegerRequired

400Error

application/json

403Error

application/json

404Error

application/json

get

/v4/track/place-info/{external_id}/

HTTPcURLJavaScriptPython

GET /v4/track/place-info/{external_id}/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "location_address": {
    "first_name": "text",
    "last_name": "text",
    "company_name": "text",
    "address_line": "text",
    "address_line_extra": "text",
    "postal_code": "text",
    "city": "text",
    "country_iso3": "text",
    "region_code": "text",
    "phone": "text"
  },
  "location": {
    "type": "Point",
    "latitude": 1,
    "longitude": 1,
    "postal_code": "text",
    "region_code": "text",
    "city": "text",
    "country_iso3": "text"
  },
  "opening_hours": [
    {
      "day": "mon",
      "open": "01:21:11",
      "close": "01:21:11"
    }
  ],
  "raw_place_type": "text",
  "courier": "text",
  "country_iso3": "text",
  "place_type": "default",
  "name": "text",
  "phone_number": "text",
  "website": "https://example.com",
  "criteria": [
    "text"
  ],
  "services": [
    "drop_box"
  ],
  "raw_services": [
    "text"
  ],
  "has_details": true,
  "is_in_service": true,
  "external_reference": "text",
  "external_id": "123e4567-e89b-12d3-a456-426614174000",
  "additional_info": {},
  "account": 1
}