{
  "service": "placeq",
  "description": "Named sets of places, one file each, that an app downloads and searches on the device. The first is coastal: beaches, bays, points, straits, islands, reefs, marinas, piers, lighthouses and towns near tidal water and a tide station.",
  "usage": [
    "GET /{set}          -- what the set's current file holds: version, count by kind, when it was built, a sample, its columns and licence",
    "GET /{set}.json     -- the same, as JSON even to a browser, which gets the set's page at /{set}",
    "GET /{set}.tsv.xz   -- the set's file, with an ETag: send If-None-Match and a month with nothing new is a 304",
    "GET /{set}/history  -- every build of the set, newest first: version, when, published, checked or refused, and what changed",
    "GET /{set}/events?since=&ids=  -- places' changes after since (the builtAt of the file you hold), oldest first, 500 a page; ids= narrows to up to 200 places, comma-separated",
    "GET /{set}/places/{id}/events  -- one place's changes, including after it was removed",
    "GET /sources        -- each set's last build, and what each upstream gave"
  ],
  "sets": {
    "coastal": {
      "title": "Coastal places",
      "description": "Named places near tidal water and a tide station: beaches, bays, points, straits, islands, reefs, marinas, piers, lighthouses and towns. About 290,000, 8 MB compressed.",
      "url": "/coastal",
      "file": "/coastal.tsv.xz",
      "attribution": "© OpenStreetMap contributors, Overture Maps Foundation; Wikidata",
      "licence": "Open Database License (ODbL) 1.0"
    }
  },
  "answer": {
    "events": "Each build compares its file with the one it replaces. A place added, removed, renamed, moved more than 100 m or given a new kind is an event: id, kind, at, seenAt, text, from and to where something moved, version, and in /{set}/events the place as subject. A score is never an event. /{set}/events pages by seenAt: ask again with next as since while more is true. The first build recorded is the baseline, with no events. Kept forever.",
    "file": "UTF-8 text, tab-separated, compressed with xz. The first line names the columns; each line after it is one place. No quoting: no field holds a tab, a newline or a |. Each set has its own columns, read by position: a new one only ever goes on the end. Rebuilt monthly, after Overture's release.",
    "search": "There is no search endpoint on purpose: search runs on every keystroke, so it runs on the device, over the file. Fold the query as keys is folded, match each word to the start of a word in keys or near, and rank by score less the log of the distance to the user."
  },
  "sources": [
    "Overture Maps base and divisions themes: OpenStreetMap's named beaches, bays, capes, straits, islands, reefs, marinas and piers, and its towns, ODbL",
    "Wikidata: lighthouses, and each place's Wikipedia sitelinks, CC0",
    "tideq's catalogue: which places are within 25 km of a tide station"
  ],
  "auth": "None. CORS is open, so a browser can call this directly.",
  "terms": "Free, unsupported, not for volume, and as is. Send a User-Agent that names your app. https://almanac.observer/#use",
  "repository": "https://github.com/gshaw/almanac/tree/main/services/placeq"
}