Developers
API referenceBusiness sign in

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

Query parameters
NameInTypeDescription
latOptionalquerynumberLatitude (required unless address is sent; alias latitude).-90 to 90
lngOptionalquerynumberLongitude (required unless address is sent; alias longitude).-180 to 180
addressOptionalquerystringNB16: search around this address instead of lat/lng (geocoded by Qoene; 422 ADDRESS_NOT_FOUND when it cannot be found).At most 300 characters
radiusOptionalqueryintegerMetres.100 to 50000Default 5000
purposeOptionalquerystringPICKUP (receiver collects, default) or DROPOFF.One of PICKUP, DROPOFF
typeOptionalquerystringDefault POINT.One of POINT, LOCKER, ALL
productOptionalquerystringSets the type; PICKUP only.One of RELAY_POINT, RELAY_LOCKER, RELAY_HOME
sizeOptionalquerystringParcel size preset.One of SMALL, MEDIUM, LARGE
weightGramsOptionalqueryintegerExact parcel weight.1 to ∞
lengthMmOptionalqueryintegerGive all three sides or none.1 to ∞
widthMmOptionalqueryintegerGive all three sides or none.1 to ∞
heightMmOptionalqueryintegerGive all three sides or none.1 to ∞
limitOptionalqueryintegerRanked results.1 to 50Default 10

Response

Success responses
StatusMeaning
200Ranked and excluded points

The body is { "status": "success", "data": … }. Fields of data (PointSearch):

Response data
FieldTypeDescription
queryOptionalobject
resultsRequiredarray of RankedPoint
excludedRequiredarray of ExcludedPoint
totalEligibleRequiredinteger
scoringRequiredobject
versionOptionalstring
weightsOptionalobject
noteOptionalstring
generatedAtRequiredstring (date-time)
geocodedOptionalobjectNB16: present when you searched by address; the position used.
textOptionalstring
latitudeRequirednumber
longitudeRequirednumber

Errors

Errors use the error envelope { "status": "error", "message", "code"?, "details"? }.

Error responses
StatusWhen
400The request is not valid. A field is missing or invalid, or the Idempotency-Key header is missing or malformed.
401Missing, invalid, expired or revoked API key. The API key is missing, invalid, expired or revoked.
403The 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).
422Eligibility 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).
429Too many requests. See the RateLimit headers. Too many requests. Wait for Retry-After, then retry with the same idempotency key.