> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve PUDO locations

> Search pick-up/drop-off points across your carriers and feed them into checkout and booking.

A PUDO location is a physical point — parcel locker, service point, post office, parcel shop — where an end-customer can drop off or pick up a parcel. `GET /v5/pudo-locations/` aggregates them across your configured carriers with standardized addresses, location types, and operating hours. The classic flow: power a "choose a pickup point" step at checkout, then pass the chosen `pudo_location_uuid` to [Create Booking](/guides/create-booking). Full parameter list: [API reference](/api-reference/v5/pudo-locations/retrieve-pudo-locations).

## Prerequisites

Carriers must be configured in **Settings > Carriers**; get their IDs for the `carrier_ids` filter from [Carrier configurations](/guides/carrier-configurations).

## Three ways to search

**By location** — fetch one specific point; `pudo_location_uuid` takes priority over every other filter:

```bash theme={null}
curl --request GET \
  --url 'https://api.perform.ai/v5/pudo-locations/?pudo_location_uuid=e2ba4f78-5246-467b-a888-4f209ba8913b' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

**By postal code** — exact-match filtering:

```bash theme={null}
curl --request GET \
  --url 'https://api.perform.ai/v5/pudo-locations/?postal_code=10115&country_code=DE&carrier_ids=dhlpak' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

**By area** — the widest net, and the recommended approach: `coordinates` (`lat,lng`) plus `radius_meters` (default 100 km). Results include `distance_meters` from your origin, ready for distance sorting. A `search` parameter accepting a free-text address does the same geocoding for you.

Narrow any search with `location_types` (carrier-original names) or `mapped_location_types` (Perform.AI standardized names — Parcel Locker, Service Point, Parcel Shop, Post Office…); the reference page lists the supported types per carrier.

<Note>
  Provide either `pudo_location_uuid` or `postal_code` + `country_code` — one of the two is required. For the broadest results, pair the postal-code search with `coordinates` and `radius_meters`.
</Note>

## Reading the results

* Pagination is page-based: `limit` 1–100 (default 25), `page` from 1; `message` reports total pages. This endpoint's envelope has no `api_response` field — `count` and `data` carry the result.
* **No match returns HTTP 200 with `count: 0`** and an empty array — unlike List Shipments, this is not a 404.
* Each location includes its operating hours three ways (`operating_hours_calc` with cutoffs per service, standardized `opening_hours`, `cutoff_hours`), plus `closing_periods` (holidays), `validity_period`, `services`, and carrier-specific `additional_info`.

## Deprecations — action needed

| Old                                                                     | New                                               | Removal                |
| ----------------------------------------------------------------------- | ------------------------------------------------- | ---------------------- |
| `uuid` (parameter and response field)                                   | `pudo_location_uuid`                              | End of **July 2026**   |
| `address.location_type`, `address.mapped_location_type` (single values) | `location_types`, `mapped_location_types` (lists) | End of **August 2026** |

Both old and new names are currently returned side by side — migrate your integration to the new names now.