# Pickup/Drop-Off Locations

## 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

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

```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token <encoded-token>`.\n\n`<encoded-token>` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"PlaceInfoLookupRequestRequest":{"description":"Place info lookup request.\n\nEither 'location' or 'external_reference' must be provided (mutually non-exclusive).","properties":{"account":{"description":"ID of account for this lookup","title":"Account ID","type":"integer"},"location":{"anyOf":[{"$ref":"#/components/schemas/GeoLocation"},{"type":"null"}],"default":null,"description":"Geographical location to search for places","title":"Location"},"external_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"","title":"External Reference"},"lookups":{"description":"List of lookups (courier, service level, criteria) to execute","items":{"$ref":"#/components/schemas/PlaceInfoLookupItem"},"maxItems":3,"minItems":1,"title":"Lookup","type":"array"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"location_address":{"$ref":"#/components/schemas/AddressSchema","description":"Address of the location, fallback for cases where the courier does not provide lookup by coordinates. Only required if explictly requested in documentation or by error message.","title":"Location Address"}},"required":["account","lookups","country_iso3"],"title":"PlaceInfoLookupRequest","type":"object"},"GeoLocation":{"properties":{"type":{"const":"Point","default":"Point","title":"Type","type":"string"},"latitude":{"description":"Latitude of this location","maximum":90,"minimum":-90,"title":"Latitude","type":"number"},"longitude":{"description":"Longitude of this location","maximum":180,"minimum":-180,"title":"Longitude","type":"number"},"postal_code":{"description":"Postal code of this location","title":"Postal Code","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":2,"title":"Region Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":35,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"}},"required":["latitude","longitude"],"title":"Geographic Location","type":"object"},"PlaceInfoLookupItem":{"properties":{"courier":{"description":"Courier code, e.g. 'fedex', 'dhl'","title":"Courier","type":"string"},"service_level":{"description":"Service level to filter locations by","title":"Service Level","type":"string"},"criteria":{"description":"Criteria for the lookup, e.g. is delivery location (hold-at)","items":{"$ref":"#/components/schemas/PlaceSearchFilter"},"title":"Lookup Criteria","type":"array"},"max_distance":{"default":20,"description":"Maximum distance to search for locations","exclusiveMinimum":0,"title":"Max Distance","type":"number"},"unit":{"allOf":[{"$ref":"#/components/schemas/UnitEnum"}],"default":"km","description":"Unit of distance to return","title":"Unit"},"limit":{"default":10,"description":"Maximum number of results to return","maximum":20,"title":"Limit","type":"integer"}},"required":["courier"],"title":"PlaceInfoLookupItem","type":"object"},"PlaceSearchFilter":{"enum":["dropoff_location","collection_point"],"title":"PlaceSearchFilter","type":"string"},"UnitEnum":{"enum":["km","mi"],"type":"string"},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"PlaceInfoLookupResponseItem":{"type":"object","description":"Place info response item augmented with distance from query point.","properties":{"location_address":{"allOf":[{"$ref":"#/components/schemas/AddressSchema"}],"description":"Address of this place"},"location":{"allOf":[{"$ref":"#/components/schemas/GeoLocation"}],"description":"Geo-location of this place"},"opening_hours":{"items":{"$ref":"#/components/schemas/OpeningHourItem"},"type":"array","description":"Opening hours of this place"},"raw_place_type":{"type":"string"},"distance":{"type":["number","null"],"format":"double","readOnly":true,"description":"Distance to the place"},"courier":{"type":"string","maxLength":255},"country_iso3":{"type":"string","description":"ISO 3166-1 alpha-3 code of the country","maxLength":255},"place_type":{"allOf":[{"$ref":"#/components/schemas/PlaceTypeEnum"}],"description":"Type of this place\n\n* `default` - Default (first party)\n* `self_service` - Self-Service / Locker\n* `partner_location` - Partner Location\n* `store` - Store\n* `other` - Other (e.g. hub)"},"name":{"type":"string","description":"Name of this place","maxLength":255},"phone_number":{"type":"string","maxLength":255},"website":{"type":"string","format":"uri","maxLength":200},"criteria":{"type":"array","items":{"type":"string","maxLength":255},"title":"Search Criteria","description":"Search Criteria that this place matches"},"services":{"type":"array","items":{"$ref":"#/components/schemas/ServicesEnum"},"description":"Services provided at this place"},"raw_services":{"type":"array","items":{"type":"string","maxLength":255},"description":"Raw (carrier-provided) services provided at this place"},"has_details":{"type":"boolean","title":"Includes Details","description":"Whether this place info includes place details"},"is_in_service":{"type":"boolean","description":"Whether this place is in service (open)"},"external_reference":{"type":"string","description":"External (3rd party) reference of this place, e.g. unique location ID","maxLength":255},"external_id":{"type":"string","format":"uuid","description":"parcelLab generated unique ID for this place"},"additional_info":{"type":"object","description":"Additional information about this place"}},"required":["country_iso3","courier","distance","location","location_address","name","opening_hours"]},"OpeningHourItem":{"properties":{"day":{"$ref":"#/components/schemas/DayOfWeek","description":"Day of the week","maxLength":3,"title":"Day"},"open":{"description":"Opening time (HH:MM)","format":"time","title":"Open","type":"string"},"close":{"description":"Closing time (HH:MM)","format":"time","title":"Close","type":"string"}},"required":["day","open","close"],"title":"OpeningHourItem","type":"object"},"DayOfWeek":{"enum":["mon","tue","wed","thu","fri","sat","sun"],"type":"string"},"PlaceTypeEnum":{"enum":["default","self_service","partner_location","store","other"],"type":"string","description":"* `default` - Default (first party)\n* `self_service` - Self-Service / Locker\n* `partner_location` - Partner Location\n* `store` - Store\n* `other` - Other (e.g. hub)"},"ServicesEnum":{"enum":["drop_box","shipping_service","international_shipping","return_service","hold_at_location","dangerous_goods","airport_location","packaging","customs","cash_on_delivery","paperless_returns"],"type":"string","description":"* `drop_box` - Drop Box / Locker\n* `shipping_service` - Shipping Services (generic)\n* `international_shipping` - International Shipping\n* `return_service` - Return-specific Services\n* `hold_at_location` - Hold at Location\n* `dangerous_goods` - Dangerous Goods\n* `airport_location` - Airport Location\n* `packaging` - Packaging\n* `customs` - Customs / Clearance\n* `cash_on_delivery` - Cash on Delivery\n* `paperless_returns` - Paperless Returns"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"}}},"paths":{"/v4/track/place-info/lookup/":{"post":{"operationId":"track_place_info_lookup_create","description":"Lookup drop-off/pick-up locations for a courier, by location & distance.","summary":"Lookup places","parameters":[{"in":"query","name":"account","schema":{"type":"array","items":{"type":"integer"}},"explode":true,"style":"form"},{"name":"ordering","required":false,"in":"query","description":"Which field to use when ordering the results.","schema":{"type":"string"}}],"tags":["Place Info"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceInfoLookupRequestRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PlaceInfoLookupRequestRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PlaceInfoLookupRequestRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PlaceInfoLookupResponseItem"}}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""}}}}}}
```

## 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

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

```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token <encoded-token>`.\n\n`<encoded-token>` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"PlaceInfo":{"type":"object","description":"Public representation of a pickup/drop-off place with geodata.","properties":{"location_address":{"allOf":[{"$ref":"#/components/schemas/AddressSchema"}],"description":"Address of this place"},"location":{"allOf":[{"$ref":"#/components/schemas/GeoLocation"}],"description":"Geo-location of this place"},"opening_hours":{"items":{"$ref":"#/components/schemas/OpeningHourItem"},"type":"array","description":"Opening hours of this place"},"raw_place_type":{"type":"string"},"courier":{"type":"string","maxLength":255},"country_iso3":{"type":"string","description":"ISO 3166-1 alpha-3 code of the country","maxLength":255},"place_type":{"allOf":[{"$ref":"#/components/schemas/PlaceTypeEnum"}],"description":"Type of this place\n\n* `default` - Default (first party)\n* `self_service` - Self-Service / Locker\n* `partner_location` - Partner Location\n* `store` - Store\n* `other` - Other (e.g. hub)"},"name":{"type":"string","description":"Name of this place","maxLength":255},"phone_number":{"type":"string","maxLength":255},"website":{"type":"string","format":"uri","maxLength":200},"criteria":{"type":"array","items":{"type":"string","maxLength":255},"title":"Search Criteria","description":"Search Criteria that this place matches"},"services":{"type":"array","items":{"$ref":"#/components/schemas/ServicesEnum"},"description":"Services provided at this place"},"raw_services":{"type":"array","items":{"type":"string","maxLength":255},"description":"Raw (carrier-provided) services provided at this place"},"has_details":{"type":"boolean","title":"Includes Details","description":"Whether this place info includes place details"},"is_in_service":{"type":"boolean","description":"Whether this place is in service (open)"},"external_reference":{"type":"string","description":"External (3rd party) reference of this place, e.g. unique location ID","maxLength":255},"external_id":{"type":"string","format":"uuid","description":"parcelLab generated unique ID for this place"},"additional_info":{"type":"object","description":"Additional information about this place"},"account":{"type":"integer"}},"required":["account","country_iso3","courier","external_reference","location","location_address","name","opening_hours"]},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"GeoLocation":{"properties":{"type":{"const":"Point","default":"Point","title":"Type","type":"string"},"latitude":{"description":"Latitude of this location","maximum":90,"minimum":-90,"title":"Latitude","type":"number"},"longitude":{"description":"Longitude of this location","maximum":180,"minimum":-180,"title":"Longitude","type":"number"},"postal_code":{"description":"Postal code of this location","title":"Postal Code","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":2,"title":"Region Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":35,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"}},"required":["latitude","longitude"],"title":"Geographic Location","type":"object"},"OpeningHourItem":{"properties":{"day":{"$ref":"#/components/schemas/DayOfWeek","description":"Day of the week","maxLength":3,"title":"Day"},"open":{"description":"Opening time (HH:MM)","format":"time","title":"Open","type":"string"},"close":{"description":"Closing time (HH:MM)","format":"time","title":"Close","type":"string"}},"required":["day","open","close"],"title":"OpeningHourItem","type":"object"},"DayOfWeek":{"enum":["mon","tue","wed","thu","fri","sat","sun"],"type":"string"},"PlaceTypeEnum":{"enum":["default","self_service","partner_location","store","other"],"type":"string","description":"* `default` - Default (first party)\n* `self_service` - Self-Service / Locker\n* `partner_location` - Partner Location\n* `store` - Store\n* `other` - Other (e.g. hub)"},"ServicesEnum":{"enum":["drop_box","shipping_service","international_shipping","return_service","hold_at_location","dangerous_goods","airport_location","packaging","customs","cash_on_delivery","paperless_returns"],"type":"string","description":"* `drop_box` - Drop Box / Locker\n* `shipping_service` - Shipping Services (generic)\n* `international_shipping` - International Shipping\n* `return_service` - Return-specific Services\n* `hold_at_location` - Hold at Location\n* `dangerous_goods` - Dangerous Goods\n* `airport_location` - Airport Location\n* `packaging` - Packaging\n* `customs` - Customs / Clearance\n* `cash_on_delivery` - Cash on Delivery\n* `paperless_returns` - Paperless Returns"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/track/place-info/{external_id}/":{"get":{"operationId":"track_place_info_retrieve","description":"Lookup drop-off/pick-up locations for a courier, by location & distance.","summary":"Retrieve Place Info","parameters":[{"in":"path","name":"external_id","schema":{"type":"string","format":"uuid","description":"parcelLab generated unique ID for this place"},"required":true}],"tags":["Place Info"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceInfo"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.parcellab.com/docs/developers/pudo-locations/pickup-drop-off-locations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.