Swarm by Foursquare

Get friends' recent check-ins near a location. Covers a recent window only (about a day), so it answers "who is out around here right now" rather than anything historical. 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}}}

Get details for a specific event. Returns {event: Event}. Default filter: {event: {id, name, allDay, startAt, endAt, date, venueId, categories}}

Get a user's friends list. 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, listItems: {count, items: [{type, venue: {id, name}, tip: {id, text}, photo: {prefix, suffix}}]}}}

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

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}}}

Get the full hierarchy of venue categories. Returns {categories: [{id: string, name: string, shortName: string, categoryCode: string, parentId: string}]}. Default filter: {categories: [{id, name, shortName, categoryCode, parentId}]}

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

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}]}}

Suggest edits to an existing venue (name, location, contact, hours, categories)

Get the weekly scoreboard (leaderboard) for a user. Returns {currentWeek: {scores: [{user: User, score: number, ranking: number}]}}. Default filter: {currentWeek: {scores: [{user: {id, displayName}, score, ranking}]}}

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. Returns {venues: [{venue: Venue, events: {items: [Event]}}]}. Default filter: {venues: [:10 {venue: {id, name}, events: {items: [{id, name, startTime, endTime}]}}]}

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. 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 a strong match. Requires ll or near. Returns {venues: [Venue], confident: boolean}. Default filter: {venues: [{id, name, location: {city, state, distance}, categories}], confident}

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

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, 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 or description. Returns {list: List}. Default filter: {list: {id, name}}

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}]}}

Get all lists for a user. Use group to filter by type.. Returns {lists: {groups: [{type: string, count: number, items: [List]}]}}. Default filter: {lists: {groups: [{type, count, items: [{id, name, 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. 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. Returns {categories: [{category: {name: string}, checkinsCount: number}]}. Default filter: {categories: [:20 {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. Returns {geos: [{id: string, name: string, type: string, venues: number, checkins: number, parentId: string}]}. Default filter: {geos: [{id, name, type, venues, checkins, parentId}]}

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}]}

Get tips written by a user. Returns {tips: {items: [Tip]}}. Default filter: {tips: {items: [{id, text, venue: {id, name}, agreeCount, createdAt}]}}

Get structured attributes for a venue (wifi, outdoor seating, credit cards, etc.). Returns {attributes: {groups: [{name: string, items: [{displayName: string, displayValue: string}]}]}}. Default filter: {attributes: {groups: [{name, items: [{displayName, displayValue}]}]}}

Get events at a venue. Returns {events: {items: [Event]}}. Default filter: {events: {items: [{id, name, startAt, endAt}]}}

Get pending flags/reports on a venue. Returns {flags: {items: [{id: string, field: string, displayName: string, displayValue: string, reporters: [User], dateTime: number}]}}. Default filter: {flags: {items: [{id, field, displayName, displayValue, reporters: [{displayName}], dateTime}]}}

Get lists that contain a venue. Returns {lists: {groups: [{type: string, count: number, items: [List]}]}}. Default filter: {lists: {groups: [{type, count, items: [{id, name, description, user: {displayName}, listItems: {count}}]}]}}