OpenStreetMap Places Monitor

Find places by category within named administrative areas using the public Overpass API. Records include all OSM tags, contact details, coordinates, attribution, and change metadata.

Input

{
  "areas": ["Ljubljana"],
  "categories": ["amenity=cafe"],
  "onlyNew": true,
  "maxItems": 200,
  "stateStoreName": "osm-places-monitor-state"
}

areas accepts 1 to 3 exact administrative area names. categories accepts 1 to 5 key=value strings. Keys and values allow letters, digits, underscores, and colons. Optional adminLevel is a string containing one or two digits. It narrows ambiguous area names. Without it, all administrative areas with the exact name match. No boundary match produces no places.

maxItems limits emitted records, from 1 to 10000. It does not limit the size of the Overpass response. Use small areas and narrow categories. Requests never tile areas.

Output and change detection

Each record has osmId, osmType, name, category, tags, lat, lon, address, phone, website, openingHours, area, osmUrl, attribution, license, licenseUrl, checkedAt, changeType, and changedFields. Missing optional values are null. Ways and relations use their bounding-box center. category is the first matching input category. Overlapping areas emit each OSM ID once, with the first matching input area.

changeType is new, changed, or unchanged. changedFields lists changed normalized fields. Changes to any tag count. Tag key order and check timestamps do not count. New records have an empty changedFields list.

With onlyNew: true, the actor emits new and changed records. With false, it also emits unchanged records. Snapshots persist only after successful pushes. Items skipped by the output limit or charging limit remain eligible next time. State is scoped to the area list, category list, and admin level. Use separate named stores for independent histories. Removal detection is not implemented.

RUN_SUMMARY in the default key-value store records fetched, eligible, and pushed counts, timestamps, charging stops, and errors. Each successful result uses the PPE event result. No separate charge call is made.

Public API limits

Requests use POST form field data, a query timeout of 60 seconds, and a client timeout of 90 seconds including body download. Requests run sequentially with at least 2 seconds between starts. HTTP 429 and 504 retry up to three times with exponential backoff and Retry-After. HTTP 429 waits at least 30 seconds. Other failures stop the run. Incomplete responses with an Overpass remark fail without updating snapshots.

The User-Agent is osm-places-monitor/1.0 (+https://apify.com/keepable_injera). See TERMS.md for the source-use decisions.

Source attribution and licence

Data is © OpenStreetMap contributors, available under ODbL-1.0. Every record carries attribution and a licence link. You must credit OpenStreetMap and disclose the ODbL licence when using the data. Distributed derived databases are subject to ODbL share-alike requirements. See the linked copyright page for details.

Local verification

Run npm install, then npm test. Tests use Node's test runner and stub network responses. Run npm start to query the real API using storage/key_value_stores/default/INPUT.json. Keep live storage separate from test storage and preserve the named state store between monitoring runs.