Finding the nearest tribe: the tribe search endpoint

POST https://api.gorilladash.com/api/v1/tribes/search answers the question "which of my tribes is nearest to this person?". Give it an address or a pair of coordinates and it returns active tribes in distance order.

It is a POST even though it only reads, so the address a visitor typed stays out of your server logs and out of the URL.

Two ways to use it

Send an identifier and it fetches that specific tribe. Send a place and it searches. Identifiers win if you send both.

Field	Notes
`tribe_id`	Fetch this tribe directly.
`tribe_slug`	Fetch by slug.
`global_id`	Fetch by your own identifier.
`address`	A free-text address. Geocoded, then searched from.
`latitude`, `longitude`	Search from these coordinates instead. More reliable than an address when you have them.
`name`	Narrow the search to tribes whose name matches.
`results`	How many to return. Defaults to 5.

{"address":"Brisbane QLD 4000","results":3}

{"latitude":-27.4698,"longitude":153.0251,"results":3}

What comes back

An array of tribes in the same shape as GET /tribes — name, slug, full address, coordinates, phone numbers including the paid and organic tracking numbers, opening hours and the square image.

The order is not simply nearest first. Any tribe whose defined territory or postcode list covers the point comes first, nearest of those first; only then are the remaining tribes added in order of distance. A tribe that is physically closer but outside every territory therefore sorts after the one whose territory the visitor is standing in — which is the answer a franchise network wants, and the one that surprises people who expected a straight distance sort.

Only active tribes are searched. A tribe that is testing or opening soon will not appear.

SEND SOMETHING TO SEARCH FROM

A request carrying no identifier, no address and no latitude + longitude pair is answered with a 400, not a 422 — the one place in this API where a bad request is not a validation error. Sending only a latitude without its longitude counts as sending neither.

When the address will not geocode

Visitors type "N/A", misspell their suburb, or enter a place that does not exist. Rather than answering with an error or an empty list, Gorilla Dash falls back to a sensible default tribe for your organisation — narrowed by name if you sent one — so your store locator still shows something.

WHY THE FALLBACK EXISTS

Every tier of the search needs a point on the map. An address that will not geocode used to resolve to coordinates of zero, zero — a spot in the Gulf of Guinea — so the locator answered with whichever tribes happened to be closest to the middle of the ocean. A deliberate fallback is far better than a confidently wrong answer.

The consequence for you: a result is not proof that the address was understood. If it matters, validate or autocomplete the address on your side before you send it, or send coordinates.

Organisation keys only

A TRIBE KEY CANNOT SEARCH

This endpoint answers 403 for a tribe key, with the message "Tribe is not supported". A tribe key only ever sees itself, so a nearest-tribe search over a single tribe has no meaning. Store locators need an organisation key.

Building a locator

Offer the visitor both a text box and a "use my location" button.
If they allow location access, send latitude and longitude. It is faster and it cannot be misread.
Otherwise send what they typed as address.
Ask for a few more results than you plan to show, so you can filter on your side without a second call.
Call it from your server, not from the browser — the API credentials must never reach a visitor.
Cache the response briefly against the search terms. Tribes move rarely and searches repeat often.

This endpoint is not cached by Gorilla Dash, because every call has a different starting point. Caching on your side is worthwhile if you get repeated searches for the same suburb.