Cerca.me

Add up to 25 places to the end of one of the user's guides (guide_id from list_my_guides or create_guide). Each place is identified like save_place: place_ref, google_maps_url, or name + near. Places without one confident match are returned with candidates and not added. On a published guide the places show up immediately. Places already on the guide are left as they are.

add_to_guide

Call this when the user asks what they and a specific person have in common, where they should go together, or what that person recommends. Compares the user's places with one friend's, optionally within a destination, and groups them: both_want_to_go (the shortlist for going together), you_want_they_recommend (the friend has been and liked it), they_want_you_recommend, both_recommend, their_recommendations and their_want_to_go (places the user hasn't saved yet), and caution (one of them rated it meh or disliked). friend is a username, a Cerca profile link, or a name matched among people the user follows (call list_friends if unsure).

compare_with_friend

Progress of a Google Maps list import started with import_google_maps_list (defaults to the most recent).

get_import_status

Details for one place: address, category, tags, hours, website, Google rating, the user's own status and note, which friends rated it, and Cerca's own editorial rating (cerca_rating) if any. Takes a place_ref from another Cerca result.

get_place

The user's taste as learned from their Cerca ratings and saves: categories and tags they gravitate to or avoid, the cities they know best, how generous their ratings are, and interests they declared. Use it to rank or explain recommendations.

get_taste_profile

Call this first whenever the user is planning a trip, visiting, or asking for recommendations in a city, neighborhood, region, or country. Returns, for that destination: places the user loved and liked, their want-to-go list, places they rated meh or disliked (never recommend these), places the people they follow liked or loved, Cerca's own editorial picks (kept separate from friends), and a summary of the user's taste. The user's own places also show which friends saved or rated them too. Pass latitude/longitude of the destination center for best coverage (Google often files places under a ward or suburb rather than the city name).

get_travel_context

Import every place in a shared Google Maps list (a maps.app.goo.gl or google.com/maps list link) into the user's want-to-go list. Runs in the background for 30-60 seconds; check progress with get_import_status. Limited to 3 imports per day.

import_google_maps_list

Add up to 25 places at once, each as want_to_go or with a rating (loved, liked, meh, disliked). Good for recording a past trip. Each item is identified like save_place: place_ref, a google_maps_url, or name + near. Items without one confident match are returned with candidates and not written; confirm those with the user and resend them with place_ref. Rating notes are public. Existing notes or ratings may be replaced, and rating a place removes it from want-to-go.

import_places

People the user follows on Cerca, with how many places each has rated and saved. Use it to turn a name like "Kyle" into a username for compare_with_friend. The official Cerca account is not a friend and is not listed.

list_friends

List the guides the user has made (curated lists of places), drafts included, most recently updated first. Pass guide_id to get one guide with its places and notes. Check here before creating a guide that may already exist.

list_my_guides