Claro AI · Use cases

Keep candidates away from your own stores

For integration engineers at a franchise or coffee chain. Upload up to 5,000 store coordinates with PUT /v1/claro/stores and exclude premises within own_stores_away_m metres of any of them.

#What is the problem?

Candidates within walking distance of an existing store waste the team's time, and the search should leave them out on its own.

#How does it work, step by step?

1. PUT /v1/claro/stores (REST) replaces the account's store list: CSV with a header naming name, lat and lon, or JSON {"stores": [{"name", "lat", "lon"}]}; up to 5,000 stores in Spain, coordinates only. A GET on the same path returns it and a DELETE removes it. There is no MCP tool for it (parity).
2. Search with the criterion own_stores_away_m (no store within that many straight-line metres, 1 to 1,000) in search_premises or POST /v1/claro/search (REST); only the account's searches read the list.
3. Read each result's state on own_stores_away_m with the other criteria. The criterion needs an exact pin.
4. For other businesses add competitors_near_max (at most max businesses of a segment or of the named chains within within_m metres, 1 to 1,000); a premises with an approximate pin gets no verdict on it.

curl -X PUT https://platform.casafari.com/v1/claro/stores \
  -H "Authorization: Bearer $CASAFARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stores": [{"name": "Plaza Mayor", "lat": 40.4155, "lon": -3.7074}]}'

#What do you get?

Search results that respect the distance from your stores, each with its state per criterion and the sentence it rests on, exact counts, and the same pm_ ids as everywhere else. A new PUT replaces the whole list, and later searches read the new one.

#What are the limits?

Up to 5,000 stores, in Spain, coordinates only. own_stores_away_m is 1 to 1,000 metres and needs an exact pin, so a premises whose address the agency hides (pin snapped to the centre of a ~500 m cell) cannot be checked against the list. competitors_max (places within a 5-minute walk) needs location data access, while competitors_near_max depends on an exact pin. PUT /v1/claro/stores can answer 400 (invalid request) or 403 (the account has no access to this) (errors).

#Related use cases

• Score every premises with your own agent
• Load every match into a CRM or warehouse nightly
• Get location figures for any point in Spain
• Keyword search from a simple form, no model
• Claro AI FAQ