Documentation menu
Watch a place for change
A watch is a question you have already asked, kept open, so the answer moving is the thing that reaches you.
Underneath every watch is one append-only feed. GET /change_event is the diff between two retained versions of a document or a rule, cited on both sides, with the date it was adopted, the date it takes effect and the date it was detected. A watch is a stored predicate over that feed, and a channel to send matches down.
In the console
Watching has two tabs. Changes is the inbox: every change event that reached you, each as the text before and the text after, with its dates. Watches lists the ones you have, with their predicate and their triggers.
The New watch card shows the sentence a watch is made of. To create one, use POST /alert, below.
Creating a watch over the API
A watch needs three things: a name, a predicate and at least one trigger. The predicate uses the same filter grammar as the collections, and is stored and returned exactly as you sent it. The fields belong to the change feed: layer, kind, jurisdiction, county and state. Exclude kind: backfill unless you want it: it marks an old rule newly added to the record, not something the town just did.
curl -X POST 'http://localhost:8000/alert' \
-H 'X-API-Key: $PLACESTACK_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: 6f1c2a90' \
-d '{
"name": "Zoning changes in Wake County",
"predicate": {
"county": { "eq": "37183" },
"layer": { "in": "use_table,control,district_map" },
"kind": { "ne": "backfill" }
},
"trigger": ["entry", "content_change"],
"channel": [{ "type": "webhook", "webhook": "whk_01h455vb4pex5vsknk084sn02q" }]
}'Triggers
entry- Something started matching the predicate.
exit- Something stopped matching it.
content_change- Something that already matched changed underneath, and still matches.
How it reaches you
A channel is webhook, email or digest. A webhook channel names a webhook you registered with POST /webhook; email and digest take an address. Give the watch a schedule (a cron expression) and a timezone to roll matches up into a digest instead of sending each one.
GET /alert/{alert}/change_event is what a watch has matched so far, which is also how you check a predicate before you point it at anyone. GET /webhook/{webhook}/delivery is the delivery log, and POST to the same path sends a signed test delivery. The console lists your webhooks but cannot yet create or test one.
Set enabled: false to pause a watch without losing it, end_time to have it stop on its own, and pass an Idempotency-Key so a retry cannot create a second copy.