> ## 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 > Searches the pick-up/drop-off locations (parcel lockers, service points, post offices, parcel shops) of your configured carriers, with standardized addresses, location types, and operating hours. Feed a selected location's `pudo_location_uuid` into Create Booking to route the label there. **Required search criteria:** provide either `pudo_location_uuid` (to fetch one location — it takes priority over every other filter) or `postal_code` together with `country_code`. For the widest results, add `coordinates` with `radius_meters` (default 100 km): filter-based search is exact-match, while area-based search returns everything in range, sorted by `distance_meters`. No match returns HTTP 200 with `count: 0` and empty `data`. **Deprecations:** the `uuid` parameter/field is replaced by `pudo_location_uuid` (removal end of July 2026); the single-value `location_type` / `mapped_location_type` address fields are replaced by the list fields `location_types` / `mapped_location_types` (removal end of August 2026). ## OpenAPI ````yaml /specs/public-api-v5.yaml get /v5/pudo-locations/ openapi: 3.1.0 info: title: Perform.AI Public API (v5) version: 5.0.0 description: |- The Perform.AI Public API lets you create and manage shipments, returns, bookings, tracking events, and documents, and retrieve reference data such as PUDO locations and carrier configurations. All endpoints accept HTTPS connections only and are secured with OAuth 2.0. Generate a Bearer access token with your API credentials (Client ID and Client Secret, from **Integrations > API** in your account), then send it in the `Authorization` header of every request. This specification covers the following endpoints: - `POST /auth/oauth/token/` - `POST /v5/shipment/` - `POST /v5/shipment/update/` - `POST /v5-2-0/shipment/update/` - `GET /v5/shipment/list/` - `GET /v5/shipment/details/` - `GET /v5-2-0/shipment/details/` - `POST /v5/events/create/` - `POST /v5/return/` - `POST /v5/return/update/` - `GET /v5/shipments/documents/` - `GET /v5/shipments/documents/{document_uuid}/` - `GET /v5/shipments/documents/labels/` - `POST /v5/booking/` - `GET /v5/pudo-locations/` - `GET /v5/carrier-configs/` servers: - url: https://api.perform.ai security: - BearerAuth: [] tags: - name: Authentication description: Generate the Bearer access token used by every other endpoint. - name: Shipments description: Create, update, search, and retrieve Shipments. - name: Events description: Add manual tracking events to Shipments. - name: Returns description: Create and update Returns and their Return Shipments. - name: Documents description: Retrieve documents attached to Shipments. - name: Booking description: Book Open Shipments with carriers and provision shipping labels. - name: PUDO locations description: Search pick-up/drop-off locations across your configured carriers. - name: Carrier configurations description: Discover the carriers configured in your account. - name: Webhooks description: Shipment update payloads Perform.AI pushes to your endpoint. paths: /v5/pudo-locations/: get: tags: - PUDO locations summary: Retrieve PUDO Locations description: |- Searches the pick-up/drop-off locations (parcel lockers, service points, post offices, parcel shops) of your configured carriers, with standardized addresses, location types, and operating hours. Feed a selected location's `pudo_location_uuid` into Create Booking to route the label there. **Required search criteria:** provide either `pudo_location_uuid` (to fetch one location — it takes priority over every other filter) or `postal_code` together with `country_code`. For the widest results, add `coordinates` with `radius_meters` (default 100 km): filter-based search is exact-match, while area-based search returns everything in range, sorted by `distance_meters`. No match returns HTTP 200 with `count: 0` and empty `data`. **Deprecations:** the `uuid` parameter/field is replaced by `pudo_location_uuid` (removal end of July 2026); the single-value `location_type` / `mapped_location_type` address fields are replaced by the list fields `location_types` / `mapped_location_types` (removal end of August 2026). operationId: get-v5-pudo-locations parameters: - name: pudo_location_uuid in: query schema: type: string format: uuid description: Fetch one specific location. Takes priority over all other filters. - name: uuid in: query deprecated: true schema: type: string format: uuid description: Legacy name for `pudo_location_uuid`. Removed end of July 2026. - name: postal_code in: query schema: type: string description: >- Postal code to search in, together with `country_code`. Required when `pudo_location_uuid` is not provided. - name: country_code in: query schema: type: string description: >- ISO 3166-1 alpha-2 country code, together with `postal_code`. Required when `pudo_location_uuid` is not provided. - name: pudo_location_id in: query schema: type: string description: Carrier-unique PUDO location ID. - name: carrier_ids in: query schema: type: string description: >- Comma-separated Perform.AI carrier IDs (from Carrier configurations) to filter by carrier. - name: coordinates in: query schema: type: string description: >- `latitude,longitude` for area search and distance calculation, e.g. `52.5200,13.4050`. - name: radius_meters in: query schema: type: integer default: 100000 description: Search radius for coordinate search. Default 100 km. - name: search in: query schema: type: string description: >- Full address string (street, number, postal code, city) used to find nearby locations and compute distance. - name: location_types in: query schema: type: string description: Comma-separated carrier-original location types to filter by. - name: mapped_location_types in: query schema: type: string description: Comma-separated Perform.AI standardized location types to filter by. - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 25 description: Locations per page. - name: page in: query schema: type: integer default: 1 description: Page number. responses: '200': description: >- Matching locations (empty `data` and `count: 0` when none). Note this endpoint's envelope has no `api_response` field. content: application/json: schema: type: object properties: message: type: string description: 'E.g. `Total pages: 2`.' count: type: integer description: Locations in this response. data: type: array items: $ref: '#/components/schemas/PudoLocation' '400': description: A filter value failed validation. content: application/json: schema: $ref: '#/components/schemas/FieldValidationError' '403': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/Throttled' '500': $ref: '#/components/responses/SystemError' components: schemas: PudoLocation: type: object description: One pick-up/drop-off location. properties: pudo_location_uuid: type: string format: uuid uuid: type: string format: uuid deprecated: true description: Legacy name for `pudo_location_uuid`. Removed end of July 2026. carrier_id: type: string description: Perform.AI 6-character carrier ID operating this location. pudo_location_id: type: string description: Carrier-unique location ID. address: $ref: '#/components/schemas/PudoAddress' lat: type: number lng: type: number distance_meters: type: - number - 'null' description: >- Distance from the provided `coordinates` or `search` address; used for distance sorting. operating_hours_calc: type: array items: type: object properties: service_name: type: - string - 'null' operating_day: type: string time_zone: type: string first_open_hours: type: - string - 'null' second_open_hours: type: - string - 'null' first_cutoff: type: - string - 'null' second_cutoff: type: - string - 'null' opening_hours: type: array items: type: object properties: day_of_week: type: string open_hour: type: string close_hour: type: string cutoff_hours: type: array items: type: object properties: service: type: - string - 'null' day_of_week: type: string cutoff_at: type: string closing_periods: type: array items: type: object properties: from_date: type: string to_date: type: string reason: type: - string - 'null' validity_period: type: object properties: from_date: type: string to_date: type: string services: type: array items: type: string additional_info: type: object description: Non-standardized carrier-specific information. updated_date: type: string FieldValidationError: type: object description: >- HTTP 400 — one or more fields failed validation; nothing was persisted. For fields inside arrays, errors are keyed by the item's position as a string ("0", "1", …), then the field name. required: - api_response - message - errors properties: api_response: type: string description: Always `"4030"`. message: type: string description: Always `validation_error`. errors: type: object description: >- Affected field → array of error messages (or a nested object for array items). PudoAddress: type: object description: Standardized address of a PUDO location. properties: location_types: type: array items: type: string description: Carrier-original location types. mapped_location_types: type: array items: type: string description: Perform.AI standardized location types. location_type: type: - string - 'null' deprecated: true description: >- Legacy single value. Removed end of August 2026 — use `location_types`. mapped_location_type: type: - string - 'null' deprecated: true description: >- Legacy single value. Removed end of August 2026 — use `mapped_location_types`. entity_reference: type: - string - 'null' address_name: type: - string - 'null' full: type: string line1: type: - string - 'null' line2: type: - string - 'null' line3: type: - string - 'null' street_name: type: - string - 'null' house_number: type: - string - 'null' postal_code: type: - string - 'null' city: type: - string - 'null' state_or_province: type: - string - 'null' region: type: - string - 'null' country: type: - string - 'null' country_code: type: - string - 'null' phone: type: - string - 'null' description: Not subscribed to notifications. GatewayError: type: object description: >- An error generated at the API gateway — authorization (`403`) or throttling (`429`). Note `api_response` is a number here, unlike application-level responses where it is a string. required: - api_response - message properties: api_response: type: integer description: '`403` or `429`.' message: type: string description: E.g. `Key not authorized`, `Quota exceeded`, `Throttled`. RequestError: type: object description: >- A request-level error such as `4000` (invalid request format), `4041` (no results found), or a `5XX` system error. required: - api_response - message properties: api_response: type: string description: Error code as a string, e.g. `"4000"`, `"4041"`, `"500"`. message: type: string responses: Unauthorized: description: >- The Bearer token is expired, invalid, or missing — or the account lacks access. content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: api_response: 403 message: Key not authorized Throttled: description: Rate limit exceeded (40 requests per second per account). content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: api_response: 429 message: Throttled SystemError: description: Internal system error. content: application/json: schema: $ref: '#/components/schemas/RequestError' example: api_response: '500' message: System error securitySchemes: BearerAuth: type: http scheme: bearer description: >- Used by every functional endpoint. Generate the token with `POST /auth/oauth/token/` and send it as `Authorization: Bearer {token}`. ````