Get account locations
Retrieve locker locations available to your account. This is the primary endpoint for external integrators (courier and delivery platforms) to list usable Bob Box locations — for example to show pickup and dropoff points on a map, or to check whether a location can fit a given parcel before creating a reservation.
Only active, non-hidden locker locations are returned by default.
Limits are imposed while an account is frozen — this endpoint then returns 403 Account is frozen.
Request
Method: GET
URL: https://api.bobbox.co.za/v2/account/locations
Query parameters
| Key | Description | Type | Required |
|---|---|---|---|
| id | One or more location IDs, passed as a JSON array (e.g. [213]). |
array of integer | No |
| name | Case-insensitive partial match on the internal location name. Not an exact match. | string | No |
| search_name | Case-insensitive partial match on either the internal name or the human_name. |
string | No |
| lat | Latitude to search near (used with max_distance). |
float | No |
| lng | Longitude to search near (used with max_distance). |
float | No |
| max_distance | Maximum distance in km from lat/lng. Leave it out and a per-location cap applies instead — see below. |
float | No |
| order_closest | If true, order results by distance from lat/lng. |
boolean | No |
| min_lat / max_lat / min_lng / max_lng | Bounding box filter, as an alternative to a radius search. | float | No |
| include_availability | If true, include a compartment_availability map showing which compartment sizes currently have space. Required to see availability at all. |
boolean | No |
| show_hidden | If true, include locations normally hidden from listings. | boolean | No |
| parcel_length / parcel_width / parcel_height | Parcel dimensions in cm. Marks a size false unless the parcel fits it. Only has an effect together with include_availability=true. |
float | No |
| volumetric_weight | Parcel volumetric weight in kg — length × width × height ÷ 4000, sides in cm. Used for fit checks when no dimensions are sent. |
float | No |
| limit | Limit the number of records returned. Must be 0 or more. | integer | No |
| offset | The number of records to skip (for pagination). Must be 0 or more. | integer | No |
| order_by | Field name to sort by. Must be a valid location field. | string | No |
| order | Sort direction, asc or desc. |
string | No |
The dimensions and include_availability work as a pair. compartment_availability is the only field the dimensions shape, and it is left out entirely unless include_availability=true. Send both, or neither.
- Both sent — a size is
truewhen a compartment of that size is free and the parcel fits it. include_availabilityalone —truemeans only that a compartment of that size is free. No fit check runs.- Either way, dimensions never remove a location. A location can come back with every size
false. Filter those out yourself.
What the map does and does not promise about POST /bob-box/reservations is documented once, in the Workflows section under "Checking space before you reserve". Read it before you rely on this field.
Sending lat and lng filters more than you asked for. Two extra rules run whenever both coordinates are present:
- A distance cap always applies. Send
max_distanceand you get that radius. Leave it out and each location is capped by its own service range instead, falling back to a platform default. The list is trimmed before you ever see it. Always sendmax_distance, so the radius is one you chose. - A service-area check runs. A location that defines a service area is dropped unless your point falls inside it. A location with no service area is always kept.
Together these mean a locker a few hundred metres away can be missing from the result. If you expect a specific locker and do not see it, fetch it by id instead of by coordinates.
Response
Status code: 200 OK Content-Type: application/json
Response body example:
See the example response.
Response fields
| Key | Description | Type |
|---|---|---|
| bob_box_locations | Array of location objects matching the query. | array |
| count | Total number of locations matching the query, ignoring limit and offset. |
integer |
Location fields:
| Key | Description | Type |
|---|---|---|
| id | Unique identifier for the location. | integer |
| name | Internal location name. Not a URL slug — both name and search_name perform case-insensitive partial matches. |
string |
| human_name | Display name for the location. Use this in customer-facing UI. | string |
| type | Always the exact string bob-box-locker on this endpoint. |
string |
| description | Free-text description, e.g. where in the building it is. | string |
| structured_address | Structured address fields. See the table below. | object |
| address | Human-readable address string. | string |
| structured_trading_hours | Per-day opening and closing times (monday…sunday, holidays). Empty start/end time means closed that day. |
object |
| trading_hours | Human-readable trading hours string. | string |
| compartment_availability | Map of compartment size to whether space is currently available. Keys are capitalised: Small, Medium, Large. Only present when include_availability=true. |
object |
| s3_image_url | Primary location image URL. | string |
| s3_image_urls | All location image URLs. | array of string |
| status | active or decommissioning. |
string |
| decommissioning_date | When the location will be decommissioned. ISO 8601 UTC timestamp, only present when status is decommissioning. See "Decommissioning locations" below. |
string (datetime) |
| hidden | Whether this location is excluded from default listings. | boolean |
| time_created | When the location was created. | string (datetime) |
| time_modified | When the location was last modified. | string (datetime) |
Structured address fields:
| Key | Description | Type |
|---|---|---|
| entered_address | The address as it was captured, unparsed. | string |
| company | Company or building name at the address. Often null. |
string or null |
| street_address | Street number and street name. | string or null |
| local_area | Suburb or local area. | string or null |
| city | City or town. | string or null |
| zone | Province. | string or null |
| code | Postal code. | string or null |
| country | Two-letter country code, e.g. ZA. |
string or null |
| lat | Latitude. | float |
| lng | Longitude. | float |
Every field except entered_address, lat, and lng can come back null, so guard before you render.
Decommissioning locations
The decommissioning_date is an ISO 8601 UTC timestamp and is only present on locations with the status decommissioning.
When a location is decommissioning:
- Reservations are still allowed up until the
decommissioning_date. - Once the
decommissioning_datehas been reached, reservations will no longer be allowed at the location.POST /bob-box/reservationsthen returns400 location is being decommissioned and is no longer accepting new reservations.
It is up to the integrator to decide how far in advance of the decommissioning_date they would like to stop making reservations to the location. Allow enough lead time for parcels to still be dropped off and collected before the locker is removed.
This endpoint only ever returns lockers. type is always the exact string bob-box-locker — not locker. The other location type, bob-box-counter, exists in the system but is filtered out here, so you never have to handle it.