API & agents

Use it from Claude or ChatGPT (MCP)

Add this as a connector using the streamable HTTP transport, with an API key as the bearer token:

https://favourite.place/api/mcp

Tools available:

• create_list — start a new list
• get_list — pull a list and its places
• browse_lists — search public lists
• search_places — find places on Google
• add_place_to_list — add by name or place id
• update_place_note — change a note
• remove_place_from_list — take one off
• reorder_list — set the ranking
• update_list — rename, describe, hide
• delete_list — remove it entirely
• export_list — KML, CSV, GeoJSON or GPX
• route_for_list — one link, the whole list as a route

Use it from your own code (REST)

An OpenAPI 3.1 description lives at /api/v1/openapi.json, which can be pasted straight into a ChatGPT custom GPT Action.

# create a list — it belongs to whoever the key belongs to
curl -X POST https://favourite.place/api/v1/lists \
  -H "Authorization: Bearer $FAVOURITE_PLACE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"title":"London'"'"'s Best Burgers","place":"London"}'

# add a place — by name; the best Google match is used
curl -X POST https://favourite.place/api/v1/lists/fim/londons-best-burgers/places \
  -H "Authorization: Bearer $FAVOURITE_PLACE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"query":"Bleecker Burger","note":"Get the double cheeseburger"}'

# export it — public lists need no credential at all
curl https://favourite.place/api/v1/lists/fim/londons-best-burgers/export/kml -o burgers.kml

Authorisation

One credential. An API key (fp_…) says who is calling, and it acts as the person it belongs to. What that person owns decides what the key may change — there is no separate per-list token.

Issue one from the command line: npm run keys:create -- <handle> "Claude". It is shown once; only its hash is stored, so a lost key is replaced rather than recovered.

The browser does not use one. The website is signed in with a session cookie, and every route accepts either — so the pages you use and the endpoints an agent calls are the same code.

One exemption, and it is narrow: fetching or exporting a single public list needs no credential, because a shared link has to work for whoever receives it and the download buttons on a shared page use those routes. It does not extend to enumeration — GET /api/v1/lists requires a key.

About exporting to Google Maps

Google publishes no API for writing places into a user's saved lists, and never has. Anything claiming to “sync a list into Google Maps” is really doing one of two things, and so are we:

• Open the list as a route. route_for_list returns one Google Maps link with each place as a stop. No import, no desktop — but Google's URL API holds eleven stops, so a longer list is truncated and says by how much.
• Import a file into Google My Maps. The KML export is built for this. The map then appears in the Google Maps phone app under Saved → Maps. Limit: 2,000 places per layer.
• Open each place and save it. Every place in the API carries a googleMapsUrl built from its Google place id, so it opens the exact restaurant rather than a fuzzy search.

For pins that work with no signal, use the GPX export with Organic Maps or OsmAnd — My Maps layers need a connection.