Locations
Ranked point search near a position
GET/locations/search
Scope locations.read
Points ranked by distance, opening state, spare space, Relay reach and operations (NB08), with exclusion reasons. Ranking is advice, not a reservation; quotes and bookings re-check the chosen point.
Request
Query parameters
| Name | In | Type | Description |
|---|---|---|---|
latOptional | query | number | Latitude (required unless address is sent; alias latitude).-90 to 90 |
lngOptional | query | number | Longitude (required unless address is sent; alias longitude).-180 to 180 |
addressOptional | query | string | NB16: search around this address instead of lat/lng (geocoded by Qoene; 422 ADDRESS_NOT_FOUND when it cannot be found).At most 300 characters |
radiusOptional | query | integer | Metres.100 to 50000Default 5000 |
purposeOptional | query | string | PICKUP (receiver collects, default) or DROPOFF.One of PICKUP, DROPOFF |
typeOptional | query | string | Default POINT.One of POINT, LOCKER, ALL |
productOptional | query | string | Sets the type; PICKUP only.One of RELAY_POINT, RELAY_LOCKER, RELAY_HOME |
sizeOptional | query | string | Parcel size preset.One of SMALL, MEDIUM, LARGE |
weightGramsOptional | query | integer | Exact parcel weight.1 to ∞ |
lengthMmOptional | query | integer | Give all three sides or none.1 to ∞ |
widthMmOptional | query | integer | Give all three sides or none.1 to ∞ |
heightMmOptional | query | integer | Give all three sides or none.1 to ∞ |
limitOptional | query | integer | Ranked results.1 to 50Default 10 |
Response
| Status | Meaning |
|---|---|
200 | Ranked and excluded points |
The body is { "status": "success", "data": … }. Fields of data (PointSearch):
| Field | Type | Description |
|---|---|---|
queryOptional | object | |
resultsRequired | array of RankedPoint | |
excludedRequired | array of ExcludedPoint | |
totalEligibleRequired | integer | |
scoringRequired | object | |
versionOptional | string | |
weightsOptional | object | |
noteOptional | string | |
generatedAtRequired | string (date-time) | |
geocodedOptional | object | NB16: present when you searched by address; the position used. |
textOptional | string | |
latitudeRequired | number | |
longitudeRequired | number |
Errors
Errors use the error envelope { "status": "error", "message", "code"?, "details"? }.
| Status | When |
|---|---|
400 | The request is not valid. A field is missing or invalid, or the Idempotency-Key header is missing or malformed. |
401 | Missing, invalid, expired or revoked API key. The API key is missing, invalid, expired or revoked. |
403 | The key lacks the scope, or the operation needs a LIVE key. The key lacks the scope, or this call needs a LIVE key (LIVE_KEY_REQUIRED), or the Business owner is not verified (SENDER_VERIFICATION_REQUIRED). |
422 | Eligibility or business rule refused the request; details.reason explains why. A business rule refused the request. details.reason.code says why (for example OVER_PRODUCT_WEIGHT_LIMIT or a point exclusion reason). |
429 | Too many requests. See the RateLimit headers. Too many requests. Wait for Retry-After, then retry with the same idempotency key. |