The Who’s On First API allows developers (and robots) programmatic access to query and retrieve Who’s On First data via a REST-ish interface.

API methods are dispatched over HTTP with one or more query parameters and data is returned in response as JSON by default but you may also specify CSV or Who’s On First’s own meta formatted responses for certain API methods.

The endpoint for the Who’s On First API is: https://whosonfirst-api.mapzen.com/

All errors are returned using HTTP status codes in the 400-599 range.

400 class errors mean the problem was on your end and 500 class errors mean the problem was our fault.

Caveats

You should treat this API as though it were in “beta”.

Which is to say: The point is for the thing to work but there are probably still some rough edges and lingering gotchas so you should adjust your expectations and your code accordingly. In the meantime have at it and please let us know if something is busted or just doesn’t feel right.

Also some methods are “more beta” than others. These methods are flagged as being experimental which means that both either their inputs or their outputs may change without warning. We’ll try not to introduce any backwards incompatible changes but you should approach these API methods defensively.

Finally the API is not feature complete yet. The easiest way to think about the Who’s On First API is to look at the Who’s On First Spelunker website and imagine that anything you can do there to search and navigate all those places should also be possible via the API. As of this writing it is not but we’ll get there. If there is anything currently missing that you’d like or need to do sooner than later send up a flare and we’ll see about adding it to the list.

API Keys

To use the Who’s On First API, you should first obtain a free developer API key.

Rate limits

See the Mapzen developer overview for more on API keys and rate limits.

Shout outs


CGI has a posse

High fives and finger guns to the Common Gateway Interface.