How this works
Oyster plots current news stories where they happen. Everything below is measured against real data rather than assumed, including the parts that do not flatter it.
Where the stories come from
Every story comes from GDELT's Global Knowledge Graph, which publishes a fresh batch of news articles every 15 minutes with the places each one mentions already extracted. Oyster reads a rolling 24-hour window of that feed and republishes the map every four hours. The timestamp under the title on the map says when the current data was built, because a claim of freshness you cannot check is not one.
GDELT is a single point of failure and there is no fallback. If it stops publishing, or changes its format, the map stops updating — it does not fail over to another source, because there is no second source with the same shape. The map would go stale rather than go wrong, and the timestamp is what would tell you.
English only, approximately
GDELT publishes two streams: original-language articles and machine-translated ones. Oyster consumes only the first, which is the entire language mechanism — there is no language detection anywhere in the pipeline.
"Untranslated" is not the same as "English," and the difference is measurable. 7.2% of headlines contain non-ASCII characters. Inspection says most of those are accented English — Anže Kopitar, El Niño — but at least one German-language publisher makes it through. The residue is small and it is not zero.
How a story gets its place
One rule decides every placement. Words like British or Danish are discarded first, because GDELT resolves them to the country and they would otherwise drag every story about a nationality to a capital city. Then the most specific place wins, unless a broader one dominates it:
- A city, park, landmark or valley mentioned more than once, and not overshadowed, becomes a pin at its exact coordinates.
- If the surrounding region is mentioned twice as often, or the country three times as often, the story is regional or national rather than local, and becomes a container instead.
- A story whose only location is a country or a state is a container from the start.
- A city mentioned exactly once is dropped, and so is a story with no usable location. Neither reaches the map.
A container is the honest form of "somewhere in here." It draws at the middle of a country or region, and clicking it outlines that region in red rather than pretending to a street address. The story card says which it is: a pin names the place, a container says somewhere in it.
Every placement on this map was made automatically, by the rule above and by nothing else. No editor checked any of them. The card used to say so on every story, in four words under the headline; it now sends you here instead, where the same fact comes with the measurement below it rather than on its own.
That last rule — dropping a city mentioned once — is the one change this project has made on independent evidence rather than its own. Such placements were judged 36.4% correct against 77.8% for everything else (Fisher exact, p = 0.023). Dropping them costs about 30% of the pins that used to be published.
Region outlines have known gaps
Region boundaries come from Natural Earth, joined to GDELT's regions by FIPS code — and that code is not unique. 187 codes are carried by more than one region. Most are harmless, but 16 cross an international border, 15 of them in the Balkans where Natural Earth's codes are stale about Kosovo, Serbia, Montenegro and North Macedonia. Only one of the 16 is reachable from real data. They are logged loudly and left alone, because "fixing" a border on one side's evidence is how you introduce a worse bug than the one you started with.
How accurate the placement is
An abort criterion was written before any of this was measured: below 50% correct, the project stops rather than ships. Placements were then sampled at random from what the pipeline actually publishes and judged by reading each headline against the place it was given, with can't tell as a real verdict, excluded from the denominator rather than counted as a win.
The most recent numbers were produced by an independent judge — someone other than the person who designed the rule — scoring a blind sheet with no trace, no expected answer, and no link to the article:
| Placement | Judged correct | 95% interval |
|---|---|---|
| Pins | 68.1% | [53.8, 79.6] |
| Containers | 83.3% | [68.1, 92.1] |
Read the interval, not the headline number. On a sample this size (47 judgeable pins) the pin figure is consistent with anything from about 54% to about 80%, and decisions here follow the lower bound rather than the point estimate. About one placement in three is wrong. The most common way it is wrong is a near miss — the right country, the wrong city — which was 52% of the errors.
What these numbers do and do not cover. This judging is what justified the drop-a-single-mention rule above — the rule was adopted because of it. So the figures describe the map as it was scored, before that rule removed the least accurate group of pins. They are the measurements on record and are not adjusted upward on the strength of a change they predate.
Which stories get shown
Far more stories exist than can be drawn legibly, so each area of the map carries only its top few, ranked by how many outlets are covering the story. At the moment roughly 57% of stories are held back at any given zoom by that budget.
There is one editorial choice in the ranking, and it is mine. Around 128 established outlets are treated as tier-1: their stories get ranking priority, and a 48-hour window instead of the usual 24, so a major story stays visible for an extra day. Nothing in the data implied this — it is a judgement about what a reader wants to see, and it is stated here because leaving it out would be the dishonest option. There is no tier-1 badge and no toggle; the preference is invisible in the UI, which is exactly why it is written down.
What was cut, and why
The original plan had a "blindspot" feature flagging stories the major outlets were ignoring. It was measured and killed: established outlets are 1.05% of GDELT's stream, and the wire services are absent entirely, so the flag fired on 98.6% of stories. A flag that fires on almost everything is not a signal. The outlet list survived and now does the opposite job — granting priority to that 1% rather than accusing the other 99%.
Two more went the same way. Pinning stories to capital cities fired on 47.7% of records and would have put a dog attack at a state capital. A graded confidence treatment on pins was refused because the measurement found no per-pin signal to grade on — so the popup says the same honest thing on every story instead.
Credits
News data from the GDELT Project. Basemap tiles from MapTiler and OpenStreetMap contributors, rendered with MapLibre GL JS. Region boundaries from Natural Earth.