goplaces-togo

Goal

Help the user pick one place to visit from their saved Google Places list by fetching live details (rating, hours, reviews) via the goplaces CLI, incorporating the user's own notes, their stated cuisine and location preferences, and their visit history — then making a clear, opinionated recommendation.

Prerequisites

• goplaces binary is installed and on PATH.
• GOOGLE_PLACES_API_KEY environment variable is set.
• Google Takeout saved places CSV — export once from https://takeout.google.com:
  1. Click "Deselect all", then check only "Saved"
  2. Click "Next step" → "Export once" → "Create export"
  3. Download the zip and find the CSV at Takeout/Saved/Saved Places.csv
  4. Give the agent the file path — it will import and remember it automatically
• A local data file at skills/goplaces-togo/goplaces-visits.json persists the imported list and visit history (created automatically on first use).

Data file schema

skills/goplaces-togo/goplaces-visits.json is the single source of truth for all persistent state:

{
  "savedList": [
    {
      "name": "string",
      "mapsUrl": "string | null",
      "placeId": "string | null",
      "city": "string | null",
      "userComment": "string | null",
      "addedAt": "YYYY-MM-DD"
    }
  ],
  "places": {
    "\x3Cplace_id>": {
      "name": "string",
      "city": "string | null",
      "visits": [
        { "date": "YYYY-MM-DD", "time": "HH:MM", "note": "string | null" }
      ]
    }
  }
}

• savedList — the user's saved places, persisted so they don't have to paste it again.
• savedList[].city — normalised city name resolved via the Places API; used to filter by city before scoring.
• places — keyed by place_id, holds visit history for recording and recency scoring.

Steps

1. Load or ask for the saved list

Read skills/goplaces-togo/goplaces-visits.json. Check whether savedList exists and has at least one entry.

If a saved list exists, show it to the user and ask:

I have your saved list from last time:

1. \x3Cname> — \x3CuserComment or "(no note)">
2. ...

Use this list, or provide a new CSV to replace it? (Press Enter to use the existing list.)

• If the user presses Enter or says "use it" / "yes" / similar affirmation → keep savedList as-is and proceed.
• If the user provides a new CSV file path or pastes CSV content → replace savedList with the newly parsed entries (see Step 2), write to disk, then proceed.
• If the user says "add" or "update" followed by a new CSV → merge: add new entries, keep existing ones that are not duplicates (match on name case-insensitively or mapsUrl). Write merged list to disk.

If no saved list exists, say exactly:

I need your Google saved places list. Here's how to get it:

1. Go to https://takeout.google.com
2. Click "Deselect all", then scroll down and check only "Saved"
3. Click "Next step" → "Export once" → "Create export"
4. Download the zip, open it, and find the CSV file inside the Saved/ folder (e.g. Saved Places.csv)
5. Share the file path or paste its contents here

Wait for the user to provide the CSV before proceeding to Step 2.

2. Parse the CSV and extract user comments

The CSV exported from Google Takeout has this header and format:

Title,Note,URL,Tags,Comment
Gochi Cupertino,,https://www.google.com/maps/place/Gochi+Cupertino/data=!4m2!3m1!1s0x808fb5c78e1841e7:0xf8efac3fb5ce0b40,,
Kunjip Tofu,Fine and good for date,https://www.google.com/maps/place/Kunjip+Tofu/data=!4m2!3m1!1s0x808fb10003a9a597:0xe41f61b5ba1b2f19,,

For each non-empty data row (skip the header and blank rows):

• Title → name
• Note → userComment (use null if empty)
• URL → mapsUrl — store as-is for reference; do not attempt to extract a place ID from the URL path, as the hex values in data=!4m2!3m1!1s\x3Chex> are Google's internal CID format, not Places API IDs
• Tags, Comment → ignore for now
• Set addedAt to today's date
• Store { name, mapsUrl, userComment, addedAt, placeId: null }

After parsing, write the resulting array to savedList in skills/goplaces-togo/goplaces-visits.json immediately, before doing any API calls. This ensures the list is never lost even if the session ends early.

3. Classify each place by city

For every entry in savedList where city is null, resolve the place name to get its city:

goplaces resolve "\x3Cplace name>" --limit 1 --json

From the result, extract the city using this priority order:

1. candidates[0].addressComponents — find the component with types containing "locality" → use its longText
2. Fall back to the component with types containing "administrative_area_level_2" → use its longText
3. Fall back to parsing the city token from candidates[0].formattedAddress (typically the second comma-separated segment, e.g. "Gochi, Cupertino, CA 95014" → "Cupertino")
4. If all fail, set city to null and note the entry as unclassified

Normalise city names to title case (e.g. "cupertino" → "Cupertino"). Store placeId from candidates[0].place_id at the same time — no need to re-resolve in Step 4.

After classifying all entries, write the updated savedList (with city and placeId filled in) back to disk.

Show the user a summary grouped by city:

Found N places across X cities:

• Cupertino (3): Gochi Cupertino, Eilleen's Kitchen, ...
• Santa Clara (2): Pho to Chau 999, ...
• Unclassified (1): Some Place Name

4. Ask which city they are in today

Say exactly:

Which city are you in today? (or press Enter to search all cities)

• If the user names a city → filter savedList to entries where city matches (case-insensitive). Use only these for scoring. If the city has zero matches, say so and ask again or offer to search all.
• If the user presses Enter or says "all" / "anywhere" → use the full savedList.
• Store the chosen city as currentCity (or null for all) in memory for this session.

5. Ask for cuisine and location preferences

Say exactly:

What cuisine or type of food are you in the mood for today? And do you have a preferred neighbourhood or area? (Press Enter to skip either.)

Wait for the user's response. Parse two optional values:

• cuisinePreference — e.g. "Japanese", "Italian", "anything spicy", null if skipped.
• locationPreference — e.g. "Shibuya", "within 2km of Shinjuku Station", null if skipped.

If the user skips both, proceed without preference filtering.

6. Resolve any remaining unresolved place IDs

Step 3 already resolved and stored placeId for newly imported entries. Only re-run resolve for entries that still have placeId: null (e.g. manually added entries):

goplaces resolve "\x3Cplace name>" --limit 1 --json

Parse the JSON. Take candidates[0].place_id. Also backfill city if it is still null. If the result is empty, mark the entry as unresolvable and skip it (report at the end).

7. Fetch details for each place ID

goplaces details \x3Cplace_id> --reviews --json

Collect the following fields for each place:

• displayName.text — human name
• currentOpeningHours.openNow — is it open right now?
• rating — overall rating (0–5)
• userRatingCount — number of reviews
• priceLevel — 0 (free) to 4 (very expensive)
• primaryType or types[] — cuisine/category tags
• location — { latitude, longitude } for distance scoring
• reviews[0].text.text — top review snippet (first 150 chars)
• editorialSummary.text — one-line editorial blurb if present

8. Load visit history

The places section of skills/goplaces-togo/goplaces-visits.json was already read in Step 1. For each place in the working list, look up its place_id in places and derive:

• visitCount — length of the visits array (0 if the key is absent).
• daysSinceLastVisit — days between today and visits[last].date (null if never visited).

9. Score and rank

Compute a score for each resolved place. All bonus terms are additive.

base  = rating * log10(max(userRatingCount, 1))
open  = openNow ? +1.0 : -2.0

# Cuisine preference bonus (apply if cuisinePreference is set)
# Check if place types or editorial summary contain the preference keyword (case-insensitive)
cuisine = cuisineMatch ? +2.0 : 0.0

# Location preference bonus (apply if locationPreference is set)
# Resolve locationPreference to lat/lng via: goplaces resolve "\x3ClocationPreference>" --limit 1 --json
# Compute haversine distance in km between place.location and preference location
# distance_km = haversine(place.lat, place.lng, pref.lat, pref.lng)
location = distance_km \x3C= 1  ? +2.0
         : distance_km \x3C= 3  ? +1.0
         : distance_km \x3C= 10 ? +0.0
         :                     -1.0
# If locationPreference is null, location bonus = 0

# User comment sentiment bonus
# If userComment is not null, read it holistically:
#   - Positive signals (e.g. "great", "love", "best", "go often") → +1.5
#   - Negative signals (e.g. "meh", "overrated", "avoid", "disappointing") → -1.5
#   - Conditional signals (e.g. "only on weekdays", "good for lunch") →
#       evaluate against current day/time; match → +0.5, mismatch → -0.5
#   - No clear signal → 0
comment = \x3Csentiment score from userComment>

# Recency penalty — discourage going to the same place too soon
recency = visitCount == 0              ? +0.5   # never visited bonus
        : daysSinceLastVisit \x3C= 7      ? -2.0
        : daysSinceLastVisit \x3C= 30     ? -0.5
        :                                 0.0

score = base + open + cuisine + location + comment + recency

Rank places by score descending. Exclude unresolvable entries from the ranking but list them at the end.

10. Recommend exactly one place

Present the top-ranked place as your recommendation using this format:

Recommended: \x3CPlace Name>

• Open now: Yes / No
• Rating: X.X / 5 (N reviews)
• Price: $ / $$ / $$$ / $$$$ (omit if unavailable)
• Your note: "\x3CuserComment>" (omit if null)
• Visits: N times (last: YYYY-MM-DD) / Never visited
• Why: \x3Cone or two sentences drawing on editorial summary, top review, user comment, and how it matches their preferences>

goplaces details \x3Cplace_id> --reviews

(Run the above to see full hours, phone, and website.)

Then list the remaining resolved places as a ranked table:

Finish with any unresolvable entries: "Could not look up: X, Y — please check the spelling or paste Google Maps URLs."

If only one place was provided, still confirm it looks good (or flag if it is closed, poorly rated, or visited very recently).

11. Confirm selection and record the visit

After showing the recommendation, ask:

Are you going to \x3CPlace Name>? Say "yes" to log this visit, or tell me which place from the list you picked instead.

Wait for the user's response.

• If the user confirms a place (by saying yes or naming one), record the visit:

  1. Read skills/goplaces-togo/goplaces-visits.json (already loaded; use in-memory copy).
  2. Ensure places["\x3Cplace_id>"] exists; create it with { name, visits: [] } if not.
  3. Append a new visit entry:

     { "date": "YYYY-MM-DD", "time": "HH:MM", "note": null }
     

     Use today's date and the current local time (24-hour format). Do not touch savedList.
  4. Write the full updated object (both savedList and places) back to skills/goplaces-togo/goplaces-visits.json.
  5. Confirm: "Logged your visit to \x3CPlace Name> on \x3Cdate> at \x3Ctime>. Have a great time!"

• If the user says no or skips, say "No worries — enjoy your day!" and do nothing.

12. Handle edge cases

• No places resolved: Tell the user none of the entries could be matched and ask them to double-check names or paste Google Maps URLs instead.
• All places closed: State that all options appear closed right now, rank by score anyway, and caveat the recommendation.
• Location resolution fails: Skip the location bonus for all places and note that the area could not be resolved.
• API error: Surface the error message and ask the user to verify GOOGLE_PLACES_API_KEY.
• History file corrupt: Warn the user, treat both savedList and places as empty, and do not overwrite until the user provides a list or confirms a visit.
• User wants to clear the list: If the user says "clear my list" or "forget my places", set savedList to [] in skills/goplaces-togo/goplaces-visits.json (keep places history intact) and confirm: "Your saved list has been cleared. Paste a new list whenever you're ready."
• User wants to remove one entry: If the user says "remove \x3Cname>", delete the matching entry from savedList by name (case-insensitive), write to disk, confirm removal. Leave places history for that place_id untouched.
• City classification fails for some entries: Proceed normally; list unclassified entries under "Unclassified" in the city summary. If the user picks a city, exclude unclassified entries from that city's pool but offer: "I also have N unclassified places — include them?"
• User's city has only one place: Recommend it directly (skip scoring), but flag if it is closed or poorly rated.

Capture behavior

These phrases can be said at any point — not just during the recommendation flow. Detect the intent and act immediately without requiring the user to be in a specific step.

Retroactive visit logging

Post-visit feedback

City browsing

List management

Preference shortcuts