Swarm by Foursquare

Report a problem with a venue, changing a public record the whole product reads. Submits a moderation flag attributed to the user, which cannot be withdrawn. It is normally reviewed by a human first, EXCEPT for callers who can resolve it themselves — flagging their own content, or holding a high superuser level — where it takes effect immediately, closing or hiding the venue for everyone. A flag returned with resolved=true was applied that way. Confirm the venue is the right one before sending. Returns {id: string, name: string, flags: {count: number, items: [{id: string, type: string, resolved?: boolean, correct?: boolean}]}}. Default filter: {id, name, flags: {count, items: [{id, type, resolved, correct}]}}

Follow or unfollow a list. The returned `following` is the resulting state, so a caller can confirm the call from the response without re-reading the list. Returns {list: List}. Default filter: {list: {id, name, following}}

Get friends' recent check-ins around a location. Covers a recent window only (about a day), so it answers "who is out around here right now" rather than anything historical. Check-ins in the same city are preferred when choosing which ones to return, but what comes back is ordered newest first, not nearest first — a result's position says nothing about how far away it is, and the tail can be well outside the area. There is no radius to narrow, and no distance to sort on. Returns {recent: [Checkin]}. Default filter: {recent: [{id, user: {id, displayName}, venue: {id, name, location: {city}}, createdAt}]}

Get details about a specific check-in. Returns {checkin: Checkin}. Default filter: {checkin: {id, createdAt, venue: {id, name, location: {city}}, shout, likes: {count}, comments: {count}, photos: {count, items: [{id, prefix, suffix}]}}}

Get full details for one event: its times, the venue it is at, description, images, provider and participants. Read allDay first to know how the times are reported — a timed event carries startAt and endAt, an all-day one carries date instead. Returns {event: Event} — plus summary, text (the description), url, images (at most one), provider, stats and participants (performers, teams or cast, each with a role), all projectable. Default filter: {event: {id, name, allDay, startAt, endAt, date, venue: {id, name}, categories: [{id, name}]}}

Get the full hierarchy of event categories. There is no parentId: each category nests its own subcategories under a categories field, the same key the top-level array uses, so the tree recurses through that one field name rather than a flat list of parent-pointers. The default projection only goes three levels deep; project categories inside categories yourself to go further if needed. Returns {categories: [{id: string, name: string, pluralName: string, shortName: string, categoryCode: string, icon: {prefix: string, suffix: string}, categories?: [<this same shape>]}]} — a node's own subcategories nest under its categories field, recursing until a leaf category has none. Default filter: {categories: [{id, name, shortName, categoryCode, categories: [{id, name, shortName, categoryCode, categories: [{id, name, shortName, categoryCode}]}]}]}

Get a user's friends list. Use offset/limit to page through results. Returns {friends: {items: [User]}}. Default filter: {friends: {items: [{id, displayName, handle, homeCity}]}}

Get details and items for a list. Special list IDs: 'self/todos' = My Saved Places, 'self/venuelikes' = My Liked Places; the same two work for another user as '{userId}/todos' and '{userId}/venuelikes'. Use offset/limit to page through results.. Returns {list: List}. Default filter: {list: {id, name, description, photo: {id, prefix, suffix}, listItems: {count, items: [{id, type, note: {text}, venue: {id, name}, tip: {id, text, venue: {id, name}}, photo: {id, prefix, suffix}}]}}}

Get details for a specific tip. Returns {tip: Tip}. Default filter: {tip: {id, text, user: {id, displayName}, venue: {id, name}, agreeCount, createdAt, photo: {id, prefix, suffix}}}

Get a user's profile. Returns {user: User}. Default filter: {user: {id, displayName, handle, homeCity, bio, friends: {count}, checkins: {count}}}

Get full details for a venue. Returns {venue: Venue}. Default filter: {venue: {id, name, location: {city}, rating, stats: {tipCount, checkinsCount}, bestPhoto: {id, prefix, suffix}, photos: {count, groups: [{type, items: [:5 {id, prefix, suffix}]}]}}}

Get the full hierarchy of venue categories. There is no parentId: each category nests its own subcategories under a categories field, the same key the top-level array uses, so the tree recurses through that one field name rather than a flat list of parent-pointers. The default projection only goes three levels deep (root, sub, subsub — the taxonomy's actual depth); project categories inside categories yourself to go further if a caller ever needs to. Returns {categories: [{id: string, name: string, pluralName: string, shortName: string, categoryCode: string, icon: {prefix: string, suffix: string}, categories?: [<this same shape>]}]} — a node's own subcategories nest under its categories field, recursing until a leaf category has none. Default filter: {categories: [{id, name, shortName, categoryCode, categories: [{id, name, shortName, categoryCode, categories: [{id, name, shortName, categoryCode}]}]}]}

Get tips/reviews for a venue. Returns {tips: {items: [Tip]}}. Default filter: {tips: {items: [{id, text, user: {id, displayName}, agreeCount, disagreeCount}]}}

Get the user's most recently reported coordinate, with the time it was recorded. Use this to supply `ll` to other tools when the client has not provided a location; check `time` before treating it as current. Returns {lat: number, lng: number, time: number}. Returns {} when no location is on record

Match free-text phrases against Foursquare's internal taxonomies — venue categories, event categories and tastes — by meaning rather than by spelling. Use it to find what the taxonomy calls something ("izakaya" -> Japanese Restaurant), to check whether a concept exists in it at all, or to get the id add_venue and propose_venue_edit take in setCategoryIds. Prefer this over get_venue_categories, which returns the whole hierarchy. This is a vector embedding search over meaning, not an exact or keyword lookup, so a spurious match is possible — a plausible-looking row that is not actually what the phrase meant, sometimes ahead of a better one further down — and an empty matches array means the taxonomy has nothing close. Matches come back best-first; sanity-check an unfamiliar or high-stakes match against its name before relying on it. Returns {conceptMatches: [{concept: string, matches: [{type: string, id: string, name: string, score: number}]}]} — one entry per requested concept, in the order sent; a concept the taxonomies have nothing for comes back with an empty matches array rather than being omitted. score is omitted by default — see the tool description — and is projectable only for debugging, not for judging a match. Default filter: {conceptMatches: [{concept, matches: [{type, id, name}]}]}

Reorder a list by moving one item directly after or before another item on the same list. Supply exactly one of afterId or beforeId. Item IDs are the ones get_list returns. The response is the list in its new order. Returns {list: List}. Default filter: {list: {id, name, listItems: {count, items: [{id, venue: {id, name}, tip: {id}}]}}}

Get lists near the current location. Returns {results: [{list: List}]}. Default filter: {results: [:20 {list: {id, name, user: {displayName}, listItems: {count}}}]}

Get venues people typically visit after this venue. Returns {nextVenues: {items: [Venue]}}. Default filter: {nextVenues: {items: [{id, name, location: {city}, categories: [{id, name}]}]}}

Suggest edits to an existing venue (name, location, contact, hours, categories), changing a public record the whole product reads. Each field accepted becomes a proposal for human review, EXCEPT for callers who can apply it themselves — editing their own content, or holding a high superuser level — where it takes effect immediately and cannot be withdrawn. A proposal returned with resolved=true was applied that way. Treat this as an edit that may be live the moment it is made, and confirm the values before sending. Returns {woes: [{id: string, type: string, resolved?: boolean}]}. Default filter: {woes: [{id, type, resolved}]}

Get the weekly scoreboard (leaderboard) for a user, ranked best first. Scores every friend, so use offset/limit to page, stopping when a page comes back empty — there is no total and no hasMore. The window applies to the current and previous week alike, and each entry carries its own ranking, so a page past the first still reports true positions. userRank is the user's own standing whichever page is asked for; userIndex locates them within the returned page and is -1 when they fall outside. Returns {currentWeek: {scores: [{user: User, score: number, ranking: number}], userRank?: string, userIndex: number}, previousWeek?: {scores: [{user: User, score: number, ranking: number}], userRank?: string, userIndex: number}} — previousWeek is sent only once a previous week has scores, is ranked separately from the current one, and is not in the default filter; project it to read it. Default filter: {currentWeek: {scores: [{user: {id, displayName}, score, ranking}], userRank, userIndex}}

Search your check-in history by venue name, date range, category, friend, geo area, or specific date (on this day). Returns {checkins: {items: [Checkin]}}. Default filter: {checkins: {items: [{id, createdAt, venue: {id, name, location: {city}}, shout}]}}

Search for events by query, date range, and location. Results are grouped by venue — one entry per venue, carrying up to three of the events found there — so a result is a venue and not an event, and both limit and offset count venues. Returns {venues: [{venue: Venue, events: {count: number, items: [{id: string, name?: string, startAt?: number, endAt?: number, categories?: [string], score: number, showtimes?: [number], provider?: {name?: string, url?: string, iconUrl?: object}}]}}]} — a reduced event rather than the Event model: no venue, allDay or date, and categories are ID strings here, not objects. Default filter: {venues: [:10 {venue: {id, name}, events: {items: [{id, name, startAt, endAt}]}}]}

Search for lists by query. Returns {lists: [List]}. Default filter: {lists: [{id, name, description}]}

Search for tips by text query, location, or category. Returns {tips: [Tip]}. Default filter: {tips: [{id, text, user: {id, displayName}, venue: {id, name}, agreeCount}]}

Search for users by name, phone, or email. Use offset/limit to page through results — there is no total and no hasMore, so stop when a page comes back empty. Returns {results: [{user: User}]}. Default filter: {results: [{user: {id, displayName, handle, homeCity}}]}

Find places near a location. Omit query to get the places the user is most likely at right now, ordered by likelihood — this is how to pick a venue to check in at. Pass query to find a place by name nearby. `confident` reports whether the top result is where the user is standing, and is present on the no-query path only — its absence on a query is not a weak match. Without a query the results also carry the parent venue of a match and venues from the wider area, so expect more than limit and some further away. Requires ll or near. Returns {venues: [Venue], confident: boolean}. Default filter: {venues: [{id, name, location: {city, state, distance}, categories: [{id, name}]}], confident}

Get venues similar to a given venue. Returns {similarVenues: {items: [Venue]}}. Default filter: {similarVenues: {items: [{id, name, location: {city}, categories: [{id, name}]}]}}

Get the venues with the most people checked in right now, around a location. Each venue carries hereNow: {count: number}, how many people are currently there, which no other tool reports. Requires either ll or near. Returns {venues: [Venue]}. Default filter: {venues: [{id, name, location: {city, distance}, categories: [{id, name}], hereNow: {count}}]}

Update an existing check-in (shout, visibility, tagged friends). Returns {checkin: Checkin}. Default filter: {checkin: {id, venue: {id, name}, shout}}

Update a list's name, description or cover photo. Send only the fields being changed — anything omitted is left as it was. photoId sets the cover to a photo such as one get_venue, get_checkin or get_tip returns, and an empty string removes it. Returns {list: List}. Default filter: {list: {id, name, description, photo: {id, prefix, suffix}}}

Edit an item already on a list in place, without removing and re-adding it: set its note, attach a tip, or set its photo. Send only what is changing; anything omitted is left as it was, and an empty string clears that field. Change the note or the tip, not both in one call — when text is sent, tipId is ignored. A photoId comes from the photos get_venue, get_checkin and get_tip return. Setting a photo leaves its visibility unchanged, so it shows on the list only to viewers allowed to see it; the first photo set becomes the list's cover if it has none. Returns {item: {id: string, note?: {text: string}, venue?: Venue, tip?: Tip, photo?: Photo}}. Default filter: {item: {id, note: {text}, venue: {id, name}, tip: {id, text, venue: {id, name}}, photo: {id, prefix, suffix}}}

Get activity feed for a specific user. Returns {activities: {items: [{type: string, createdAt: number, summary: {entities, text: string}}]}}. Default filter: {activities: {items: [:10 {type, createdAt, summary}]}}

Get venues the user has liked. Use offset/limit to page through results.. Returns {venues: {items: [Venue]}}. Default filter: {venues: {items: [{id, name, location: {city}, categories: [{id, name}]}]}}

Get a user's lists, grouped by the caller's relationship to each list. To page, send the previous response's cursor; stop when hasMore is false. Narrow to one group to page within it. 'yours' holds the user's saves and likes as lists, whose ids get_list accepts. Returns {lists: {cursor?: string, hasMore: boolean, groups: [{type: string, items: [List]}]}} — a group reports no count; page with cursor until hasMore is false. Default filter: {lists: {cursor, hasMore, groups: [{type, items: [{id, name, description, user: {displayName}, listItems: {count}}]}]}}

Get a user's current mayorships and contending mayorships. Returns {mayorships: [{venue: Venue, summary: string, mayor?: User}], contendingMayorships: [{venue: Venue, summary: string, mayor?: User}]}. Default filter: {mayorships: [:20 {venue: {id, name, location: {city}}, summary}], contendingMayorships: [:10 {venue: {id, name, location: {city}}, summary}]}

Get a user's check-in stats broken down by venue category, busiest first. Use offset/limit to page through results — there is no total and no hasMore, and a short page does not mean the last one, so stop when a page comes back empty. ancestorCategoryId restricts to categories that are, or descend from, any of the given category id(s) — e.g. the id for "Asian Restaurant" returns the sushi places and Chinese restaurants the user has checked into, not a rolled-up Asian Restaurant total. Returns {categories: [{category: {name: string}, checkins: number, venues: number}]}. Default filter: {categories: [{category: {name}, checkins, venues}]}

Get a user's check-in stats broken down by event category, busiest first. Use offset/limit to page through results — there is no total and no hasMore, and a short page does not mean the last one, so stop when a page comes back empty. ancestorCategoryId restricts to categories that are, or descend from, any of the given event category id(s). Returns {categories: [{category: {name: string}, checkinsCount: number}]}. Default filter: {categories: [{category: {name}, checkinsCount}]}

Get a user's check-in stats broken down by friend (who they check in with). Returns {friends: [{user: User, checkinsCount: number}]}. Default filter: {friends: [:20 {user: {displayName}, checkinsCount}]}

Get a user's check-in stats broken down by geographic area, one entry per country/state/city/neighborhood checked into. Returns a flat array by default, each entry carrying parentId (absent for a top-level entry) instead of nested children — pass flat=false for the nested shape instead, where each entry has children instead of parentId. woeType narrows which levels appear at all, in either shape: a skipped level's entries reparent to the nearest level still included, so the result stays a valid tree or a correctly linked flat list either way. ancestorGeoId restricts to the given geo id(s) and everything under them, at any depth — the id(s) themselves included, so a country's id returns that country along with its states and cities. limit/offset page over a stable order that works the same in either shape (parent immediately before its own descendants); there is no total and no hasMore, and a short page does not mean the last one, so stop when a page comes back empty. Returns {geos: [{id: string, name: string, type: string, venues: number, checkins?: number, ne: [number, number], sw: [number, number], img?: string, parentId?: string}]} — the flat (default) shape; with flat=false each entry has children?: [Geo] nested instead of parentId. checkins is present only when reading your own stats. type is one of country, state, city, neighborhood

Get a user's check-in stats broken down by venue (most visited places). Returns {venues: [{venue: Venue, checkinsCount: number}]}. Default filter: {venues: [:20 {venue: {name}, checkinsCount}]}