> This page is for Agent Handler.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Foursquare

**Authentication:** OAuth. See [Magic Link](/merge-agent-handler/features/magic-link) for the runtime auth flow, or [Application credentials](/merge-agent-handler/admin-setup/add-oauth-credentials) to bring your own OAuth app.

## Sample use cases

* Find coffee shops near the SF office with a 4+ rating, open right now.
* List sushi restaurants within 1km of 1600 Pennsylvania Ave with takeout.
* Show me the most popular venues in the Mission this weekend.

## Available Tools

#### create\_checkin

Check in at a venue. Use search\_venues to find venue IDs. Optionally add a shout message.

#### get\_checkin

Get checkin details including venue, shout, likes, and comments.

#### delete\_checkin

Delete a checkin. Only the creator can delete their own checkins.

#### create\_list

Create a new Foursquare list. Optionally set description and collaborative mode.

#### get\_list

Get list details including items (venues). Use get\_self\_lists to find list IDs.

#### update\_list

Update a list's name, description, or collaborative setting.

#### delete\_list

Delete a list. Only the creator can delete their own lists.

#### add\_list\_item

Add a venue to a list. Use search\_venues for venue IDs. Optionally add text.

#### delete\_list\_item

Remove an item from a list. Use get\_list to find item IDs.

#### autocomplete

Autocomplete for venues and places. Provide query with optional ll or near for location bias.

#### get\_recommendations

Get venue recommendations near a location, optionally filtered by query. Provide ll or near.

#### add\_tip

Add a tip to a venue (max 200 chars). Use search\_venues to find venue IDs.

#### get\_tip

Get tip details including text, venue, author, and likes.

#### delete\_tip

Delete a tip. Only the author can delete their own tips.

#### get\_self

Get the authenticated user's profile including name, home city, checkin/list/tip counts.

#### get\_self\_checkins

Get the authenticated user's checkin history with pagination. Filter by before/after timestamps.

#### get\_self\_lists

Get the authenticated user's lists. Filter by group: created, edited, followed, friends, suggested.

#### get\_self\_tips

Get tips the authenticated user has written. Sort by recent, nearby, or popular.

#### get\_self\_tastes

Get the authenticated user's taste preferences (e.g., 'craft beer', 'sushi', 'live music').

#### search\_venues

Search venues by location+query. Provide ll or near. Use get\_categories for category IDs. Returns paginated results.

#### get\_venue

Get venue details by ID including location, categories, ratings, hours, and stats. Use search\_venues to find IDs.

#### get\_venue\_photos

Get photos for a venue. Build URLs: prefix + \{width}x\{height} + suffix. Use offset for pagination.

#### get\_venue\_tips

Get tips for a venue. Sort by friends, recent, or popular. Use offset for pagination.

#### get\_venue\_hours

Get operating hours for a venue with timeframes and open/close times.

#### get\_venue\_attributes

Get venue attributes like outdoor seating, Wi-Fi, live music, parking, and more.

#### get\_categories

Get all venue categories as a hierarchical tree with IDs and names. Use category IDs to filter search\_venues.

#### get\_trending\_venues

Get trending venues near a lat/lng coordinate. Returns venues with high recent activity.