Read API · MCP · open corpus · v1

Build on the open place corpus

A JSON read API and an MCP server over 2,516,198 places in 524 cities. Every response carries the licence, the attribution, the citation and — for a place — the providers that attest it with their own licences. There is no key to obtain for the free tier, and the whole database is also a free download: the corpus is the product, not a preview of it.

Access, free tier and paid at scale

The free tier is a rate limit on the service. The database itself is never metered: charging for API access while the corpus stays downloadable is what ODbL §4.6 permits.

The API

Base URL: https://maps.555.team. The OpenAPI 3.1 document is /api/v1/openapi.json. Errors are {"error":{"code","message"}} with a 400 for a bad parameter, 404 for a missing record and 503 with cache-control: no-store when the catalogue is unavailable — never a 500 for input.

GET /api/v1/places — list places

Filter by bbox (west,south,east,north), category and name query; keyset pagination with next_cursor; page cap 100.

curl -s 'https://maps.555.team/api/v1/places?bbox=2.29,48.85,2.31,48.86&category=restaurant&limit=5' | jq '{count, next_cursor, licence, attribution, first: .places[0]}'

GET /api/v1/places/{place_id} — one place

The full record, its providers, per-field provenance, the OSM hours group when a value exists, and the count of published contributions.

curl -s 'https://maps.555.team/api/v1/places/gers:5fb48aff-e828-4fa3-b2d3-af8ef900f217' | jq '{licence, place: {place_id: .place.place_id, name: .place.name, sources: .place.sources, contributions: .place.contributions}}'

GET /api/v1/best?city=&category= — best in city

The ranked group the /best pages render, in the pipeline’s order, with the rank method and its validation.

curl -s 'https://maps.555.team/api/v1/best?city=hong-kong-hk&category=restaurant' | jq '{city: .city.name, category: .category.phrase, rank: .rank.method, top: .places[0] | {rank, place_id, name, score}}'

GET /api/v1/cities — cities

The indexed cities with their group and candidate counts, plus the corpus coverage from the dump manifest.

curl -s 'https://maps.555.team/api/v1/cities' | jq '{count, groups, ranked_places, coverage, first: .cities[0]}'

GET /api/v1/openapi.json — OpenAPI

The machine-readable contract for exactly the endpoints above.

curl -s 'https://maps.555.team/api/v1/openapi.json' | jq '.paths | keys'

The MCP server

Streamable HTTP, JSON-RPC 2.0, at https://maps.555.team/mcp. Tools: search_places, best_in_city, place_detail, city_info. Every tool result carries the place ids, the licence and the attribution in structuredContent.

# initialize
curl -s 'https://maps.555.team/mcp' -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

# the tools
curl -s 'https://maps.555.team/mcp' -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# one call
curl -s 'https://maps.555.team/mcp' -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"best_in_city","arguments":{"city":"hong-kong-hk","category":"restaurant"}}}'

A notification (notifications/initialized) answers 202 with no body. The server is stateless: no session id is minted.

Dataset card

Coverage. 2,516,198 places, 524 cities, 106 countries; 5,697,744 provider rows in place_source; 123,982 places with OpenStreetMap opening hours; 0 published contributions. Build 1893dbba69aa, produced 2026-10-22T02:16:27Z in 69.4s. The world shard is 295.0 MB; the largest city shard is tokyo-jp (111,373 places).

Opening hours. 123,982 places carry an OpenStreetMap opening_hours value (ODbL-1.0), with the OSM element and the matching gate; /api/v1/places/{place_id} returns that group as hours when it exists.

Refresh cadence. On demand today — a build is cut from the live catalogue when the data changes, and a nightly rebuild is the next step. Every build is content-addressed, so a schedule changes nothing about the URLs: `build.built_at` is the instant of the run and `build.id` is a hash of the shard bytes, which means two builds over unchanged data are the same build.

Licence per field group

Providers and their licences

The ranking, and what is validated

rank_score is curation quality, not popularity: how well attested and how complete a record is. The answer artifact publishes the weights for transparency: {"attest":0.35,"complete":0.25,"confidence":0.2,"designation":0.4,"fame":-0.15,"chain":-0.3}. The limit: no licensable popularity signal; this ranks curation quality, not taste. Nobody paid for placement.

The independent check is Wikivoyage (CC BY-SA 4.0, validation-only): 5,951 matched anchors in 294 cities; 5,651 anchors fall in 1,554 groups. Median percentile 73.0; share in the top decile 24.2%; share ranked first 2.9%.

What is NOT validated. An anchor only exists where Wikivoyage and the catalogue name the same place, so the matched set is biased toward well-attested places - which the rank rewards through `attest`. Every number here is a lower bound on the ranking's agreement with editorial selection, not an unbiased estimate of it. The Michelin check is partly circular (designation is a term the rank already rewards): 533 matched, median percentile 100, but partly circular: 17 of the 5,951 Wikivoyage anchors carry the designation term this rank rewards (designation +0.40) and sit at a median percentile of 99.93, against 72.55 for the 5,934 matched anchors without it. A validation set that shares a term with the model measures the term, not the model. Heritage has one anchor: too few to validate anything. There is no human taste panel and no rating source; opening hours come from OpenStreetMap and are parser-accepted, not verified against the venue. Families below the anchor floor carry a count and are explicitly not validated.

How to cite

maps.555.team (2026). Open place corpus, version v1 (build 1893dbba69aa). https://maps.555.team/data

@misc{maps555corpus, title = {maps.555.team open place corpus}, author = {{maps.555.team}}, year = {2026}, note = {Version v1, build 1893dbba69aa, ODbL-1.0}, url = {https://maps.555.team/data}}

Honest limits

• No ratings, review counts or prices: the catalogue has no licensable source for them.
• Opening hours (OSM, ODbL-1.0) are published only when the parser accepts the value and the place matched by identity or a normalised name plus a 75 m gate; a missing value is not evidence that a venue is closed.
• The corpus is a derivative database of OpenStreetMap: the whole database is ODbL-1.0 and “© OpenStreetMap contributors” must be credited.
• Coverage is uneven by city and category; confidence is the provider's, not ours.
• City assignment is a nearest-city-point join (GeoNames), not municipal polygons.
• basic_category is a classifier label; the ranked pages use a curated noun phrase, not a guarantee of scope.
• A contribution is public only while status = 'published'; private lists and favourites are never published.
• The rank orders curation quality, not taste. It is not a review score and must not be presented as one.
• The API free tier is a rate limit; a bulk consumer should download the corpus instead.

The repository copy of this card is docs/dataset-card.md.

Crawlers

/docs, /data and /best are indexable: the licence and the answers are meant to be read. /api/v1/* and /mcp are noindex — a machine interface, not a search result — and robots.txt says so explicitly. The map itself stays closed.