Shortlink

The shortlink option in the share tab

A shortlink is a link to a map, designed to be shorter than the normal URL. It can be generated by selecting the Shortlink option on the Share tab.

Example

• https://www.openstreetmap.org/#map=9/51.5110/0.0550 - a wide view of the London area.
  • https://osm.org/go/0EEQjE-- - same view, shorter link.
• https://osm.org/go/0EEQjEEb - zoomed in a lot on a small area of the above image. Note the common beginning.

How the encoding works

8x8 division of the world with the character used for each square in OSM shortlink encoding

The URL is composed of https://osm.org/go/ followed by a binary quadtile address, encoded in ASCII (modified base64), with chars at the end to indicate relative zoom.

Each character encodes the location on a 8x8 chessboard, the first character is the location on the whole globe, next character is the location within that square, etc.

The binary address - for example 0101 - is used as follows:

1. Imagine the lowest zoom tile - this contains the whole globe.
2. Now - the first bit is 0, this indicates it's the left half of the tile.
3. The second bit being 1 indicates it's the bottom left half in combination with the first bit.
4. The second two bits work the same, further refining the location to the tile that is one sixteenth of the area of the world-tile, on the very bottom-left. (Antarctica, From 45 degrees south down to the pole, and from 90 degrees west to 180 degrees west)

This binary address is then encoded in ASCII by modified-base64, and a few chars are added at the end to indicate relative zoom. The length of the code gives the zoom level rounded to the nearest 3 and the appended code specifies the remainder.

Marker

A marker pin reference for the centre of the map can be added to the shortlink by appending "?m", or by ticking the "Include marker" checkbox on the share tab, or if an alternative map layer or any other query has already been included use "&m". Using one of the above examples, https://osm.org/go/0EEQjE--?m will give the above view with a marker in the centre, https://osm.org/go/0EEQjE--?layers=T&m will give the above view but with the Transport layer selected and a marker in the map centre.

Code for encoding & decoding

You can perform your own shortlink encoding and decoding, and it's worth noting that this is the fundamental advantage of using this URL format over other URL shortening services, where you are dependent on the continuity of that service. With these short links, the location information is truly encoded in the URL, and you can decode it algorithmically, without any database look-up, and independently of OpenStreetMap's servers. Unlike URL shortening services, we're not "using up" combinations of letters. We'll never need to make the URLs longer.

The reference code for encoding and decoding shortlinks is short_link.rb on github. Other implementations include:

• application.js is an older encoder once used on the website. As of September 2021 it represents the current algorithm, but any future changes will make it obsolete. (It's not removed -- it was just refactored into the leaflet binding).
• shortlink.js - JavaScript encoder, uses BigInt to simplify the interlacing step
• salesianer.de - gives the code in JavaScript additionally for decoding + implementation in Perl
• osm_shortlink.py - Is a Python implementation (and decode)
• shortlink.py - Complete and efficient Python implementation, with optional Cython support
• MapUtils.java - Has a java implementation included in Osmand
• osm_shortlink.erl - Erlang implementation of encoding
• osm_shortlink.ex - Elixir implementation as hex package
• osmshortlink-go - Go (Golang) module for usage from Go code and command-line tool (with binaries for various platforms)
• osmGeoHash - PHP implementation
• osm-shortlink - Rust implementation with Python bindings

If anyone has other language implementations, please feel free to link them here. We cannot guarantee the correctness of such code.

History of change

• 2009-06-26: shortlink introduced.
• 2009-07-03: zoom adjustment character changed from "=" to "-". Decoder still supports older format.
• 2011-11-25: "@" character in b64 encoding replaced with "~" due to Twitter issues. Decoder still supports older format.

See also

• Browsing#Sharing a link to the maps - general user help on all the various linking options.
• Layer URL parameter - details of this particular parameter
• Permalink - similar feature that produces longer urls