Changes in area
changes_in_areaRead-onlyIdempotent
Find what opened, closed, or changed in a named area or bounding box by comparing two Overture map releases, with counts and category breakdowns.
Instructions
What's opened or closed around here since a past Overture release.
Use this for "what's new around here", "what's closed since spring",
or any question with a time dimension — every other tool here answers
against a single, current snapshot of the data; this is the only tool
that compares two.
Area, exactly one of:
- place: a free-text area name ("Palo Alto"), resolved with this
server's usual free-text area matching (prominence-ranked, "City,
ST" suffix aware). The resolved division is echoed back as "area"
on the response. A name
matching several equally-ranked divisions returns {"error":
"ambiguous_area", "candidates": [...]} rather than silently picking
one; an unresolvable name returns {"error": "not_found"}. If the
resolved division is too large to diff (bigger than this tool's
per-side degree cap — countries, large regions), returns a
{"error": "bad_request"} naming the area and suggesting a smaller
one (a neighborhood or district instead of a whole city/region) or
an explicit bbox.
- min_lon/min_lat/max_lon/max_lat: an explicit bbox (all four
together, or none) — for when the caller already has coordinates
rather than a name. Same size cap as the named-area path.
category, when given, filters both releases' scans identically before
diffing — see diff_places; a place that changed OUT of the category
between releases reads as "disappeared" from this filtered view, which
is the correct reading of "restaurants that changed", not a bug.
from_release/to_release: Overture release strings (YYYY-MM-DD.N). Omit
both to diff the previous release against the ACTIVE one — to_release
defaults to release.resolve_release(), the same release every other
tool in this conversation queries (env pins included), and
from_release defaults to the newest listed release older than it: an
adjacent, recent window. Not the oldest release Overture still serves
— years-old releases are schema-drifted enough that most compared
columns NULL out and everything reads as "changed"; pass explicit
releases for a wider window, and check "degraded_fields" on the
response when you do. Pass both to pick a
specific window; passing only one is a {"error": "bad_request"}. When
the release listing is reachable, an explicit release not in it is
also a {"error": "bad_request"} rather than a silent typo'd diff; when
the listing itself is unreachable (network trouble), explicit releases
are tried directly instead — they may still resolve even though the
list couldn't be built.
If neither release is given and no listed release is older than the
active one (a listing failure, or a world with only one live release),
this returns a structured {"error": "upstream_unavailable"} naming
whatever releases WERE found — never an empty diff that would read as
"nothing changed here" when the real answer is "the window couldn't be
built".
limit caps how many ranked rows each of appeared/disappeared/changed
carries (default 8, hard cap 25 — the same per-answer row bound every
other tool here uses); "counts" and the "*_by_category" breakdowns are
never reduced by it.
Returns a compact digest, not the full diff: headline "counts"
(appeared/disappeared/changed/unchanged, always exact within the
scanned bound), a `limit`-capped ranked slice of each of
appeared/disappeared/changed (id, name, category, confidence, lat,
lon — changed rows carry old_name/new_name and
old_category/new_category instead of name/category), a small
per-bucket "*_by_category" breakdown computed over everything the
scans saw (same denominator as "counts", not the limit-capped slice),
the "releases" window actually used, "degraded_fields" when either
release's schema is missing a compared column (that field was NULL on
that side, so treat "changed" with suspicion), and
"truncated"/"omitted_count" when more exists than fits
(omitted_count sums omissions across the three lists).
Honest framing (issue #309): a "notes" list is attached whenever it
applies — a disappearance may be delisting or data cleanup, not a
closure; an appearance may be newly-mapped, not newly-opened. Neither
claim is inferable from this data alone, so the digest says so rather
than implying otherwise.
Returns a structured {"error": ...} if upstream is unavailable or the
active places dataset is missing the id/bbox columns this tool depends
on, for either release.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| place | No | ||
| max_lat | No | ||
| max_lon | No | ||
| min_lat | No | ||
| min_lon | No | ||
| category | No | ||
| to_release | No | ||
| from_release | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||