---
title: "Stale locations: matching and API reference"
description: "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."
type: "reference"
audience: [network-manager, advertiser, publisher, developer]
keywords: [stale location, name matching, successor place, confidence, AI suggestions, stale-locations.do, replace.do, remove.do, suggestions.do, count.do, CONFIRM_REQUIRED, NOT_STALE, stale_locations tool]
ui_path: "Account → Advertisers / Publishers → action rail → Stale locations"
---

Fetch the complete documentation index at: https://epom.com/ad-server/docs/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Stale locations: matching and API reference

Reference for [Clean up stale location targeting](https://epom.com/ad-server/docs/guides/targeting/stale-locations.md): 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](https://epom.com/ad-server/docs/api/targeting-api.md).

## 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](https://epom.com/ad-server/docs/api/mcp.md).

## Related

- [Clean up stale location targeting](https://epom.com/ad-server/docs/guides/targeting/stale-locations.md)
- [Add, edit, and remove targeting rules](https://epom.com/ad-server/docs/guides/targeting/add-targeting.md)
- [Targeting rules via API](https://epom.com/ad-server/docs/api/targeting-api.md)