Open Street Map Change Tracker

🗺️ OpenStreetMap Places Finder is a powerful Apify Actor designed to discover, track, and collect point-of-interest data directly from OpenStreetMap's own public Overpass API. This tool provides comprehensive OpenStreetMap Places intelligence including OSM element ID, element type, coordinates, and full OSM tag data for any amenity keyword within a defined geographic bounding box. Whether you're building a local business directory, mapping amenity coverage in a region, or conducting geospatial research, the OpenStreetMap Places Finder delivers actionable OpenStreetMap Places insights efficiently.

With multi-mirror Overpass API querying, automatic failover and retry handling, flexible bounding-box targeting, and reliable Apify Dataset delivery, the OpenStreetMap Places Finder ensures comprehensive OpenStreetMap Places coverage across any list of amenity keywords and geographic area. It focuses on key OpenStreetMap Places signals including amenity type, coordinates, and OSM tags, making it an essential tool for geospatial and local business research.

---

📋 Table of Contents

• Features
• Data Source
• How It Works
• Input
• Output
• Technical Stack
• Data Fields
• Use Cases
• Quick Start
• Configuration
• Performance
• Important Notes
• License & Legal

---

🔥 Features

• Direct Overpass API Access – Queries OpenStreetMap's official Overpass API directly for fast, structured OpenStreetMap Places data.
• Multi-Mirror Failover – Automatically tries multiple Overpass API mirrors (overpass-api.de, Mail.ru, Kumi Systems) in sequence if one is unavailable.
• Retry-Resilient Requests – Automatically retries each mirror on 504 Gateway Timeouts and other errors with increasing backoff delays.
• Amenity Keyword Matching – Searches for any combination of OSM amenity tag values (e.g., cafe, restaurant, pharmacy) using regex-style matching.
• Bounding Box Targeting – Restricts results to a precisely defined geographic rectangle via min/max latitude and longitude.
• Node, Way & Relation Coverage – Queries all three OSM element types for comprehensive OpenStreetMap Places coverage.
• Centroid Resolution – Returns a usable latitude/longitude for way and relation elements via Overpass's out center mode.
• Full Tag Extraction – Preserves every OSM tag on each matched element for maximum data richness.
• Proxy-Aware Configuration – Supports Apify proxy configuration for future use, while correctly bypassing it for Overpass (which is public and proxy-sensitive).
• Real-Time Dataset Push – Pushes the full result set to Apify Dataset in a single batch.

---

📊 Data Source

OpenStreetMap Overpass API

• Authority: The OpenStreetMap project's official Overpass API, accessed via multiple public mirrors
• Access Method: Direct async HTTP POST requests via aiohttp, using Overpass QL query syntax
• Coverage: Any publicly mapped OpenStreetMap Places element tagged with a matching amenity value within the given bounding box
• Data: Structured JSON element data including type, coordinates, and full OSM tag set
• Access: Public API, no API key required
• Update Frequency: Reflects OpenStreetMap's current live map data at time of run

---

⚙️ How It Works

The OpenStreetMap Places Finder accepts a list of amenity keywords, a geographic bounding box, and an area label, then builds an Overpass QL query matching nodes, ways, and relations whose amenity tag matches any of the given keywords within that bounding box. The Actor sends this query to the first Overpass API mirror, retrying on 504 timeouts and other errors with increasing backoff; if all retries on one mirror fail, it automatically moves on to the next mirror in the list. Once results are returned, each element is normalized into a clean record containing its OSM ID, type, resolved coordinates (using the element's own lat/lon or its computed center for ways/relations), and full tag dictionary. The complete result set — along with keyword, area, and bounding box context — is pushed to the Apify Dataset as a single output record.

Key Processing Steps:

1. Input Parsing – Accept amenity keywords, a bounding box, and an area name
2. Query Construction – Build an Overpass QL query matching nodes, ways, and relations by amenity tag within the bounding box
3. Mirror Loop – Attempt the query against each Overpass API mirror in sequence
4. Retry Handling – Back off and retry on 504 Gateway Timeouts and other transient errors per mirror
5. Failover – Move to the next mirror if all retries on the current one are exhausted
6. Element Normalization – Extract OSM ID, type, coordinates (direct or centroid), and tags for each result
7. Output Assembly – Combine all elements with keyword, area, bounding box, and status metadata
8. Dataset Push – Push the full result set to the Dataset in a single batch

Key Benefits:

• Pull OpenStreetMap Places data for any amenity type without manually querying Overpass
• Cover an entire geographic area in one request via bounding-box targeting
• Get resilient results even when individual Overpass mirrors are down or slow
• Feed local business directories, geospatial research pipelines, or mapping dashboards
• Automate recurring OpenStreetMap Places snapshots for a region of interest

---

📥 Input

The Actor accepts the following input parameters:

Field	Type	Default	Description
keywords	string	"cafe,restaurant"	Comma-separated list of OSM amenity values to match.
bbox	object	London bbox	Bounding box with min_lat, min_lon, max_lat, max_lon.
area_name	string	"London"	Label describing the target area, included in the output.
useApifyProxy	boolean	true	Configured for future use; not applied to Overpass requests.
apifyProxyGroups	array	["RESIDENTIAL"]	Proxy group configuration (not used for Overpass).

Example Input:

{
  "keywords": "cafe,restaurant,pharmacy",
  "bbox": {
    "min_lat": 51.28,
    "min_lon": -0.489,
    "max_lat": 51.686,
    "max_lon": 0.236
  },
  "area_name": "London"
}

Search a Different City's Bounding Box:

{
  "keywords": "bar,pub",
  "bbox": {
    "min_lat": 40.4774,
    "min_lon": -74.2591,
    "max_lat": 40.9176,
    "max_lon": -73.7004
  },
  "area_name": "New York City"
}

---

📤 Output

The Actor pushes a single OpenStreetMap Places result record with the following structure:

Field	Type	Description
osm_elements	array	List of matched OSM elements (see below)
total_elements	integer	Total number of matched OpenStreetMap Places elements
keywords	array	The amenity keywords used for this search
area	string	The area label provided in the input
bbox	object	The bounding box used for this search
last_updated	string	ISO 8601 timestamp of when the run completed
status	string	"success" or "error"

Each object inside osm_elements contains:

Field	Type	Description
osm_id	integer	The element's unique OpenStreetMap ID
type	string	OSM element type: "node", "way", or "relation"
lat	float	Latitude (direct or computed centroid)
lon	float	Longitude (direct or computed centroid)
tags	object	Full dictionary of OSM tags for the element

Example OpenStreetMap Places Output Record:

{
  "osm_elements": [
    {
      "osm_id": 123456789,
      "type": "node",
      "lat": 51.5074,
      "lon": -0.1278,
      "tags": {
        "amenity": "cafe",
        "name": "Example Coffee House",
        "opening_hours": "Mo-Su 07:00-19:00"
      }
    }
  ],
  "total_elements": 1,
  "keywords": ["cafe", "restaurant"],
  "area": "London",
  "bbox": {"min_lat": 51.28, "min_lon": -0.489, "max_lat": 51.686, "max_lon": 0.236},
  "last_updated": "2026-08-29T09:00:00.000Z",
  "status": "success"
}

---

🧰 Technical Stack

• HTTP Client: aiohttp for async requests to Overpass API mirrors
• Query Language: Overpass QL for structured node/way/relation queries
• Async: asyncio for non-blocking, multi-mirror request handling
• Date Handling: datetime for UTC timestamping
• Proxy: Apify Proxy configured but intentionally not applied to Overpass requests (public API, proxy causes 504s)
• Logging: Apify Actor logging system
• Platform: Apify Actor serverless environment

---

📊 Data Fields Explained

Element Identity

• osm_id: The unique identifier assigned by OpenStreetMap
• type: Whether the element is a point (node), path/area (way), or grouped feature (relation)

Location

• lat / lon: The element's coordinates — direct for nodes, computed centroid for ways/relations

Attributes

• tags: The complete set of OSM tags describing the place (name, amenity type, hours, address, etc.)

Search Context

• keywords / area / bbox: The parameters used to produce this result set
• last_updated: When this snapshot was collected

---

🎯 Use Cases

• Local Business Directory Building – Populate a directory of cafes, restaurants, or other amenities in a region
• Geospatial Research – Study amenity density and distribution across a bounding box
• Market Research – Gauge the presence of specific business types in a target area
• Urban Planning Research – Analyze public amenity coverage for a city or district
• Academic Research – Study OpenStreetMap data patterns at scale
• App/Map Prototyping – Source real point-of-interest data for a location-based app prototype

---

🚀 Quick Start

1. Prepare Input

Go to Apify Console and enter:

{
  "keywords": "cafe,restaurant",
  "area_name": "London"
}

2. Run the Actor

Click Start. The Actor will:

• Build an Overpass QL query from the given keywords and bounding box
• Query Overpass API mirrors with automatic retry and failover
• Normalize all matched elements into a clean output structure
• Push the full result set to the Dataset

3. Monitor Progress

Console shows:

Keywords: ['cafe', 'restaurant']
Area: London | BBox: (51.28, -0.489, 51.686, 0.236)
Fetching OSM data from Overpass API...
  [overpass-api.de] Attempt 1/3...
Fetched 342 elements.
Done! Pushed 342 elements to dataset.

4. View & Download Results

• Results Tab: The OpenStreetMap Places result record
• Export: JSON, CSV, Excel, or HTML
• Filter: By element type or tag values
• API Access: Available via the Apify API

---

⚙️ Configuration

Default London search:

{
  "keywords": "cafe,restaurant"
}

Custom area and keywords:

{
  "keywords": "bar,pub",
  "bbox": {
    "min_lat": 40.4774,
    "min_lon": -74.2591,
    "max_lat": 40.9176,
    "max_lon": -73.7004
  },
  "area_name": "New York City"
}

Single amenity type:

{
  "keywords": "pharmacy",
  "area_name": "London"
}

---

📈 Performance

Processing Speed

• One Overpass query per run, covering all keywords and the full bounding box at once
• Retry backoff of attempt × 5 seconds on transient errors per mirror
• Response time scales with bounding-box size and amenity density — larger areas take longer

Resource Usage

• Memory: Low to moderate, depending on the number of elements returned for large bounding boxes
• Network: One primary request per run, with additional retries/mirror attempts only on failure
• Proxy: Not used for Overpass requests by design, even when configured

---

⚠️ Important Notes

Legal & Compliance

• Fair Use: Uses Overpass API's public mirrors as intended, with backoff on rate-limiting responses
• Public Data Only: Retrieves only publicly available OpenStreetMap data, licensed under the Open Database License (ODbL)
• Attribution: OpenStreetMap data requires attribution ("© OpenStreetMap contributors") when displayed or redistributed
• Legal: Not legal advice — consult qualified professionals before using this data for compliance-sensitive decisions

Data Quality

• Freshness: Reflects OpenStreetMap's current live data at time of run — a crowd-sourced dataset that varies in completeness by region
• Completeness: Coverage depends entirely on how thoroughly the target area has been mapped by OSM contributors
• Accuracy: Sourced directly from the Overpass API; tag quality and completeness vary by contributor
• Verification: Cross-check high-stakes location or business details against other sources before relying on them

Best Practices

• Keep bounding boxes reasonably sized to avoid Overpass timeouts on very dense or very large areas
• Use specific amenity keywords to keep result volume relevant and manageable
• Re-run periodically to get a fresh snapshot, since this Actor does not track changes between runs
• Always attribute OpenStreetMap when publishing or redistributing this data
• If a mirror is consistently failing, allow the Actor's built-in failover to try the next one rather than intervening manually

---

📄 License & Legal

Terms of Use:

• Use for legitimate research, mapping, and business directory purposes
• Comply with the Open Database License (ODbL) and provide OpenStreetMap attribution
• Respect Overpass API's fair-use guidelines
• Use OpenStreetMap Places data responsibly and in compliance with applicable laws

Disclaimer: OpenStreetMap Places Finder is provided as-is for research and mapping purposes. It returns a point-in-time snapshot of matching places — it does not detect or report changes between runs. Users are responsible for compliance with OpenStreetMap's ODbL license, Overpass API fair-use guidelines, and all applicable laws. This is not legal advice.

---

⚖️ OpenStreetMap Places Excellence

This Actor is optimized for OpenStreetMap Places research with:

• ✅ Multi-mirror Overpass API access with automatic failover
• ✅ Retry-resilient requests with backoff
• ✅ Full node/way/relation coverage with centroid resolution
• ✅ Bounding-box precision targeting
• ✅ Real-time Dataset push
• ✅ Production-ready code