spacetimeid

spacetimeid is very simple web application to encode and decode unique 64-bit numeric identifiers for a combined set of x, y and z coordinates.

Another way to think about it is as a unique ID for any given point at a specific time anywhere on Earth.

For example, the corner of 16th and Mission, in San Francisco, at around midnight the night/morning of March 17, 2010 would be encoded like this:

<rsp stat="ok">
	<spacetime y="37.764832" x="-122.419304" z="1268809061" id="4726418083411316312844298485971"/>
</rsp>

To decode a unique ID back in to space and time coordinates, you'd do this:

<rsp stat="ok">
	<spacetime y="37.764832" x="-122.419304" z="1268809061" id="4726418083411316312844298485971"/>
</rsp>

You can also encode WOE IDs and time by going to the /woe endpoint. Here is The Mission, early morning of the 17th:

<rsp stat="ok">
	<spacetime woeid="55970963" id="4236329328336141596" timestamp="1268809061"/>
</rsp>

It is also possible encode IP addresses. Here is (more or less) the same corner, at the same time, in IP space:

<rsp stat="ok">
	<spacetime ip="173.164.158.185" id="2372987648121137443" timestamp="1268809061"/>
</rsp>

Decoding WOE IDs and IP adddresses the same as decoding coordinates but just make sure you go to the correct endpoint: /woe/decode and /ip/decode respectively.

some details

• The IDs are clustered together along Hilbert curve using Steve Witham's Python libraries. What's a Hilbert curve you ask? Nick Johnson describes them this way:

  Suppose instead, we visit regions in a 'U' shape. Within each quad, of course, we also visit subquads in the same 'U' shape, but aligned so as to match up with neighbouring quads. If we organise the orientation of these 'U's correctly, we can completely eliminate any discontinuities, and visit the entire area at whatever resolution we choose continuously, fully exploring each region before moving on to the next. Not only does this eliminate discontinuities, but it also improves the overall locality. The pattern we get if we do this may look familiar - it's a Hilbert Curve.

• x and y are assumed to be longitude and latitude coordinates, respectively. Because the Hilbert functions required positive integers longitudes are offset by 180 degrees and latitudes by 90. (This is just so you know what's happening in the black box, the inputs and outputs will always be plain old lat, lon points.) Both coordinates are rounded to 8 decimal points.

• z is assumed to be a Unix timestamp which make the whole thing problematic for events before January 01, 1970. This is not a feature and is being investigated.

• By default spacetimeid returns responses as XML. If you'd prefer JSON, just append ?format=json to your request.

further reading

• spacetimeid, Aaron Straup Cope

• Phi, Lambda and (Slightly Embarassing) Temporality, Gary Gale

• Designing for Spacetime, Matt Jones