# Foursquare Scraper — Venue & Places Discovery (`crawlerbros/foursquare-scraper`) Actor Discover venues and places worldwide using OpenStreetMap data - search cafes, restaurants, hotels, shops and 200+ place types by keyword, category and location. Returns rich metadata: address, phone, website, opening hours, cuisine type and more. - **URL**: https://apify.com/crawlerbros/foursquare-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Developer tools, Integrations, Agents - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Foursquare Scraper — Venue & Places Discovery Discover venues and places worldwide with rich location data. Search cafes, restaurants, hotels, shops, hospitals, and 35+ other venue types by keyword, category, or geographic coordinates. Powered by OpenStreetMap data — free, global, and no API key required. ### What it does - **Search by keyword** — find any venue by name (e.g., "Starbucks", "pizza", "coworking space") - **Browse by category** — list all cafes, restaurants, hotels, gyms, museums, etc. near a location - **Trending venues** — popular tourist and landmark venues in any area - Returns rich metadata: address, phone, website, opening hours, cuisine type, wheelchair access, payment methods, and more ### Input | Field | Type | Description | |---|---|---| | `mode` | select | `search` (default), `byCategory`, `trending` | | `searchQuery` | string | Keyword to search (e.g., `coffee shop`, `Marriott`), used with mode=search. Optional — leave blank to return all named venues near the location | | `near` | string | City or place name (e.g., `New York`, `London`, `Tokyo`) | | `latitude` | number | Latitude (alternative to `near`) | | `longitude` | number | Longitude (alternative to `near`) | | `venueCategory` | select | Category filter: cafe, restaurant, bar, hotel, museum, etc. | | `radius` | integer | Search radius in meters (100–50000, default 5000) | | `includeNodes` | boolean | Include point features (default true) | | `includeWays` | boolean | Include building-footprint features (default false) | | `maxItems` | integer | Max results (1–500, default 50) | #### Example inputs **Search coffee shops in New York:** ```json { "mode": "search", "searchQuery": "coffee shop", "near": "New York", "maxItems": 20 } ```` **Browse all restaurants in London:** ```json { "mode": "byCategory", "venueCategory": "restaurant", "near": "London", "radius": 3000, "maxItems": 50 } ``` **Trending spots in Paris by coordinates:** ```json { "mode": "trending", "latitude": 48.8566, "longitude": 2.3522, "radius": 5000, "maxItems": 30 } ``` ### Output Each record contains: | Field | Description | |---|---| | `venueId` | Unique OSM element ID (e.g., `node/746176794`) | | `name` | Venue name | | `alternativeName` | Alternate/short name, when OSM has one | | `primaryCategory` | Main category label (e.g., `Cafe`, `Restaurant`) | | `categories` | All applicable category labels | | `address` | Street address | | `city` | City | | `state` | State or region | | `postalCode` | Postal/ZIP code | | `country` | Country code | | `fullAddress` | Combined address string | | `lat` | Latitude | | `lng` | Longitude | | `phone` | Phone number | | `email` | Email address | | `website` | Official website URL | | `facebook` | Facebook page URL, when published | | `instagram` | Instagram profile/URL, when published | | `openingHours` | Hours in OSM format (e.g., `Mo-Fr 08:00-20:00`) | | `cuisine` | Cuisine type for food venues | | `internetAccess` | Internet/Wi-Fi availability, when tagged | | `brand` | Brand/chain name | | `operator` | Operator name | | `description` | Free-text description, when published | | `wheelchairAccess` | Wheelchair accessibility (`yes`/`limited`/`no`) | | `paymentMethods` | Accepted payment methods | | `outdoorSeating` | Outdoor seating, when tagged (e.g. `yes`, `sidewalk`, `garden`) | | `takeaway` | Take-away / to-go availability, when tagged (`yes`/`no`/`only`) | | `delivery` | Delivery availability, when tagged (`yes`/`no`/`only`) | | `wikipedia` | Linked Wikipedia article, when tagged | | `wikidata` | Linked Wikidata ID, when tagged | | `venueUrl` | OpenStreetMap page URL | | `sourceUrl` | Source URL | | `scrapedAt` | UTC timestamp | | `recordType` | Always `venue` | #### Sample output record ```json { "venueId": "node/746176794", "name": "Starbucks", "primaryCategory": "Cafe", "categories": ["Cafe", "Coffee Shop"], "address": "2525 Broadway", "city": "New York", "state": "NY", "postalCode": "10025", "country": "US", "lat": 40.7938, "lng": -73.9728, "phone": "+1 212-000-0000", "website": "https://www.starbucks.com", "openingHours": "Mo-Su 06:00-22:00", "cuisine": "Coffee Shop", "brand": "Starbucks", "wheelchairAccess": "yes", "paymentMethods": ["credit cards", "debit cards"], "venueUrl": "https://www.openstreetmap.org/node/746176794", "sourceUrl": "https://www.openstreetmap.org/node/746176794", "scrapedAt": "2026-06-30T10:00:00+00:00", "recordType": "venue" } ``` ### Supported categories cafe, restaurant, bar, nightclub, hotel, shop, supermarket, pharmacy, bank, atm, hospital, cinema, theatre, museum, library, place\_of\_worship, school, university, fuel, parking, gym, spa, beauty\_salon, fast\_food, pub, food\_court, ice\_cream, bakery, bicycle\_rental, car\_rental, taxi, bus\_station, train\_station, airport, ferry\_terminal, post\_office, police, fire\_station, embassy ### Frequently Asked Questions **How does this work?** This actor uses OpenStreetMap's Overpass API to query venue data. Nominatim is used to geocode city names to coordinates. Both services are free and require no API key. **Is there a usage limit?** OpenStreetMap services impose soft rate limits. The actor handles this automatically with retries and delays. For large-scale queries, reduce `maxItems` or narrow your `radius`. **How current is the data?** OpenStreetMap data is community-maintained and updated continuously. Most venues in major cities have recent data. **Can I search globally?** Yes — the `near` field accepts any city or place name worldwide: "Tokyo", "Dubai", "Buenos Aires", etc. **What's the difference between modes?** - `search`: Best when you know the venue name or keyword. Searches by name across all types. - `byCategory`: Best when you want all venues of a specific type (e.g., all hospitals). - `trending`: Best for discovering tourist attractions, historic sites, and popular spots. **Why might some venues be missing a phone or website?** OpenStreetMap data coverage varies. Smaller or newer venues may have fewer details. The actor only returns fields that are available in the data. # Actor input Schema ## `mode` (type: `string`): What to fetch. ## `searchQuery` (type: `string`): Free-text keyword to search for (e.g. "coffee shop", "Italian restaurant", "Starbucks"), used with mode=search. Optional — if left blank, mode=search returns all named venues near the location. ## `near` (type: `string`): Location to search near, e.g. "New York", "London", "Tokyo". Alternatively use latitude+longitude. ## `latitude` (type: `number`): Latitude for coordinate-based search (use instead of `near`). Example: 40.7128. ## `longitude` (type: `number`): Longitude for coordinate-based search (use instead of `near`). Example: -74.0060. ## `venueCategory` (type: `string`): Filter or browse by category. Use with mode=byCategory to browse all venues of that type. ## `radius` (type: `integer`): Search radius from the center point in meters. Default 5000 (5 km). ## `includeNodes` (type: `boolean`): Include point-geometry features (individual venue markers). Default true. ## `includeWays` (type: `boolean`): Include polygon-geometry features (buildings mapped as areas). Default false for faster results. ## `maxItems` (type: `integer`): Maximum number of venues to return. ## Actor input object example ```json { "mode": "search", "searchQuery": "coffee shop", "near": "New York", "venueCategory": "cafe", "radius": 5000, "includeNodes": true, "includeWays": false, "maxItems": 50 } ``` # Actor output Schema ## `venues` (type: `string`): Dataset of all scraped venue records. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "search", "searchQuery": "coffee shop", "near": "New York", "venueCategory": "cafe", "radius": 5000, "includeNodes": true, "includeWays": false, "maxItems": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/foursquare-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "search", "searchQuery": "coffee shop", "near": "New York", "venueCategory": "cafe", "radius": 5000, "includeNodes": True, "includeWays": False, "maxItems": 50, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/foursquare-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "search", "searchQuery": "coffee shop", "near": "New York", "venueCategory": "cafe", "radius": 5000, "includeNodes": true, "includeWays": false, "maxItems": 50 }' | apify call crawlerbros/foursquare-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/foursquare-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Foursquare Scraper — Venue & Places Discovery", "description": "Discover venues and places worldwide using OpenStreetMap data - search cafes, restaurants, hotels, shops and 200+ place types by keyword, category and location. Returns rich metadata: address, phone, website, opening hours, cuisine type and more.", "version": "1.0", "x-build-id": "Uk2bN2Dcxf3b9qaFm" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~foursquare-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-foursquare-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~foursquare-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-foursquare-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~foursquare-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-foursquare-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "byCategory", "trending" ], "type": "string", "description": "What to fetch.", "default": "search" }, "searchQuery": { "title": "Search query", "type": "string", "description": "Free-text keyword to search for (e.g. \"coffee shop\", \"Italian restaurant\", \"Starbucks\"), used with mode=search. Optional — if left blank, mode=search returns all named venues near the location.", "default": "coffee shop" }, "near": { "title": "Location (city or place name)", "type": "string", "description": "Location to search near, e.g. \"New York\", \"London\", \"Tokyo\". Alternatively use latitude+longitude.", "default": "New York" }, "latitude": { "title": "Latitude", "minimum": -90, "maximum": 90, "type": "number", "description": "Latitude for coordinate-based search (use instead of `near`). Example: 40.7128." }, "longitude": { "title": "Longitude", "minimum": -180, "maximum": 180, "type": "number", "description": "Longitude for coordinate-based search (use instead of `near`). Example: -74.0060." }, "venueCategory": { "title": "Venue category", "enum": [ "cafe", "restaurant", "bar", "nightclub", "hotel", "shop", "supermarket", "pharmacy", "bank", "atm", "hospital", "cinema", "theatre", "museum", "library", "place_of_worship", "school", "university", "fuel", "parking", "gym", "spa", "beauty_salon", "fast_food", "pub", "food_court", "ice_cream", "bakery", "bicycle_rental", "car_rental", "taxi", "bus_station", "train_station", "airport", "ferry_terminal", "post_office", "police", "fire_station", "embassy" ], "type": "string", "description": "Filter or browse by category. Use with mode=byCategory to browse all venues of that type.", "default": "cafe" }, "radius": { "title": "Search radius (meters)", "minimum": 100, "maximum": 50000, "type": "integer", "description": "Search radius from the center point in meters. Default 5000 (5 km).", "default": 5000 }, "includeNodes": { "title": "Include nodes (point features)", "type": "boolean", "description": "Include point-geometry features (individual venue markers). Default true.", "default": true }, "includeWays": { "title": "Include ways (building footprints)", "type": "boolean", "description": "Include polygon-geometry features (buildings mapped as areas). Default false for faster results.", "default": false }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of venues to return.", "default": 50 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```