📘

Cache — Cache-Control: public, max-age=3600 (1 hour)

Part of the catalog — The product catalog explains how merchants, products, calendars and timeslots fit together.

Why this endpoint exists

Two jobs that broad search cannot do:

Field-boosted text matching. A hit on the merchant's name ranks above a hit in its description, so "Zoo" puts Amsterdam Zoo first instead of every merchant whose blurb mentions animals. If broad search returns technically-correct but badly-ordered results, this is the fix.

"Near me". Filter to merchants within a radius of a coordinate and get the distance back on each result, so you can build a map view or a "closest first" list.

Parameter combinations

This endpoint has a required-parameter rule that is easy to get wrong: you must supply either query, or all three of lat, lon and distance. The geo trio is all-or-nothing.

The combined mode is the one to reach for on a "search near me" UI. Note it is a conjunction: a strong text match 50 km outside the radius is excluded entirely, not ranked lower.

How to use it

# Text search, name-boosted
curl "https://api.acc.funtrips.io/v2/merchants/search?query=zoo&limit=20" \
  -H "x-campaign-id: $CAMPAIGN_ID"

# Within 25 km of Amsterdam Centraal
curl "https://api.acc.funtrips.io/v2/merchants/search?lat=52.3791&lon=4.9003&distance=25000&limit=20" \
  -H "x-campaign-id: $CAMPAIGN_ID"

# Both
curl "https://api.acc.funtrips.io/v2/merchants/search?query=zoo&lat=52.3791&lon=4.9003&distance=25000&limit=20" \
  -H "x-campaign-id: $CAMPAIGN_ID"

Query parameters

❗

distance is in metres

Passing 25 gives you a 25-metre radius and an empty result set that looks like a data problem. This is the single most common mistake on this endpoint.

distance_meters on the response

When you supply coordinates, each merchant carries an extra field:

{
  "id": "8a2f4c61-9d3e-4b57-a0c8-1e5f7b2d9a30",
  "title": "Amsterdam Zoo",
  "distance_meters": 1840,
  "…": "the usual Merchant fields"
}

It is straight-line distance, not travel distance — good for sorting and for "1.8 km away", wrong for "8 minutes by car". The field is absent entirely when no coordinates were sent, so do not depend on its presence.

Everything else matches the Merchant shape from list merchants, including the best_effective_price / best_list_price pair.

Errors

As with broad search, always send limit — an unbounded search is the usual cause of a 504. No matches is 200 with an empty array.