Stale locations: matching and API reference
How the Stale locations page decides that a place is stale and what it is called now — name matching, the AI's limits, confidence — plus every REST call, response field, skip reason and error code, and the MCP tools.
Reference for Clean up stale location targeting: how a place is judged stale and matched to its current name, and the REST and MCP surface behind the page.
How a place is judged stale
A place is stale only when the geo service’s own lists prove it unknown — its country, region or city list was read and the name is not there. Names are compared as the geo service compares them: case does not matter, accents and spaces do. When the service does not answer, answers for too few places, or nearly every place fails at once, the check is reported as unavailable instead, and nothing is listed. A region named in a country the provider lists no regions for is stale — an empty list is an answer, not an outage.
The places looked up are remembered for about ten minutes; the count the rail button reads is up to five minutes old (a minute while the geo service is not answering). Opening the page, removing or replacing a rule, or saving or removing a location or country rule on a targeting card refreshes it at once.
How a current name is found
Names are compared first against the geo database’s own lists — the same lists the place picker offers — ignoring case, accents, hyphens and old Nordic spellings (Taastrup and Tåstrup), and a few administrative words (County, Region, Kommune, Stationsby, Kirkeby…). A city whose region is gone is looked for under up to 80 of the country’s regions, which catches a renamed region; in a country with more, a city not found there is called no current place only with low confidence.
| Confidence | Given when |
|---|---|
| High | The name matches a listed place spelled another way (Taastrup → Tåstrup), or the stale name without its administrative word matches one (Oslo County → Oslo, Tommerup Stationsby → Tommerup); or the city was found again under its own renamed region. |
| Medium | Both names match only with their administrative words set aside, or the city was found under a different region than before. Also the ceiling for any AI answer. |
| Low | A city whose region is gone in a country with more than 80 regions, or an AI answer that said it was unsure — shown as No current place matches this name. |
Only the places names leave open go to the AI, which may pick a place only from that same list, or answer that none is the place. It may also name the town a village or neighbourhood lies in (North Sandwich is part of Sandwich now), but only when it is sure which town that is; a town with a similar name, a bigger town nearby or a place in another region is not offered as a match. When in doubt it answers that no place matches. A place the AI picked from outside the list counts as answered, as no current place. AI answers are kept in the server’s memory for up to a week (a restart forgets them); opening Fix with AI again asks only about places not yet answered.
Reasons shown on a card: Spelled differently now, Name shortened, Region renamed, Renamed, X is part of Y now, No current place matches this name, No current place matches this name exactly, A country code cannot be replaced, only removed, The geo service did not answer for this place.
The AI part needs the assistant permission on your role, the assistant switched on for the network, an AI key, and budget left this month; each match costs like a short assistant request on the same key and budget. Without any of these, places are matched by name only and the panel says which was missing.
Over the API
GET /rest-api/targeting/stale-locations.do answers the same list as the page: status, counts,
and rows with kind per rule (SAFE, OPENS_ALL, STARTS_DELIVERY).
GET /rest-api/targeting/stale-locations/count.do answers only how many rules block delivery
(OPENS_ALL or STARTS_DELIVERY) per side — demand and supply — from the same check up to
five minutes old that the rail button reads. Asking it when a page loads is cheap, but after any
change to a location or country rule the next count scans the whole network again, so do not poll
it in a loop.
POST /rest-api/targeting/stale-locations/remove.do takes targetIds and removes only rules of
kind SAFE unless confirmChanges=true; the rest come back in skipped with reason
CONFIRM_REQUIRED.
POST /rest-api/targeting/stale-locations/replace.do takes targetId, countryCode,
regionName and cityName. It answers 503 while the geo service does not answer and 404 for a
rule removed since the list was read. Pass targetIds instead to replace several rules naming the
same stale place with the same include or exclude in one request; rules no longer stale come back
in skipped, and a list mixing places or rules is refused with 400 before anything changes.
Picking the very place the rule already names is refused (That is the place the rule names
already) and nothing is changed; country rules cannot be replaced, only removed.
GET /rest-api/targeting/stale-locations/suggestions.do answers one group per stale place and
include or exclude, with its targetIds and a suggestion (action REPLACE with countryCode,
regionName, cityName ready for replace.do, REMOVE or KEEP; reason, reasonText,
confidence, source), from names and earlier answers only — it never calls the AI. POST to the
same path is what Fix with AI sends: it also asks the AI about the places names leave open, and is
billed like the assistant.
skipped reason | Meaning |
|---|---|
CONFIRM_REQUIRED | Removing it changes delivery; pass confirmChanges=true. |
NOT_STALE | Not a stale place you can manage, or already removed. |
FORBIDDEN | Your role cannot change this rule. |
FAILED | Removed by someone else meanwhile, or the database refused; it was left as it was. Try again. |
Every removal and replacement goes through the same path as an edit on the targeting card: it is written to the action log and reaches the ad servers like any other targeting change. See Targeting rules via API.
MCP tools
The AI assistant and MCP clients use the stale_locations and stale_locations_fix tools, which
ask before any change that affects delivery; stale_locations with suggest=true also says what
each place is called now — see MCP.
