The Traveller Map site works by having a browser-based client application written in JavaScript call various APIs provided by the web site to render map tiles, provide search results, look up coordinates, and so forth. The browser provides the HTML+CSS rendering, layout and interaction engine, the web site provides the content, and the script glues it together.
All of these APIs may be called by other applications. In addition, several other APIs have been exposed specifically for external applications or users to take advantage of.
If you start developing against these APIs in any form, please let me know! Email me at inexorabletash@hotmail.com. In addition, the blog is a good source of news and discussion around the site and APIs.
NOTE: Many APIs take x and y parameters. The coordinate system for those values varies depending on the API. See the Coordinate Systems documentation for more details.
All of the APIs that produce images (Poster, JumpMap, Tile) as well as the site itself (including IFRAME) take a options parameter that is a bit-map of rendering style options.
The options are canonically defined in the script as flags that can be combined by adding the values together. The options parameter must be specified in decimal.
| Option | Hexadecimal | Decimal | Notes |
|---|---|---|---|
| SectorGrid | 0x0001 | 1 | |
| SubsectorGrid | 0x0002 | 2 | |
| SectorsSelected | 0x0004 | 4 | At low scales, show only some sector names |
| SectorsAll | 0x0008 | 8 | Show all sector names |
| BordersMajor | 0x0010 | 16 | |
| BordersMinor | 0x0020 | 32 | Deprecated |
| NamesMajor | 0x0040 | 64 | |
| NamesMinor | 0x0080 | 128 | Not used |
| WorldsCapitals | 0x0100 | 256 | |
| WorldsHomeworlds | 0x0200 | 512 | |
| RoutesSelected | 0x0400 | 1024 | Not used |
| PrintStyle | 0x0800 | 2048 | Specifying PrintStyle and CandyStyle is undefined. |
| CandyStyle | 0x1000 | 4096 | |
| ForceHexes | 0x2000 | 8192 |
The easiest way to determine the options is to use the main map page, select map options using the controls on the right, then click Permalink on the bottom - this will reload the page with the current view coordinates and options in the URL. Then copy the options parameter from the URL.
Different APIs use different coordinate systems. Future API updates may attempt to unify them, but the different coordinate systems will always be required, as different APIs provide different views on the site dataset.
Some APIs support simple named locations, namely the name of a sector followed by a four-digit hex number (in xxyy form). This is inefficient, as the sector must be looked up by name, but is supported for convenience in APIs likely to be specified as URLs directly by humans rather than automatically generated.
The Traveller Map database of sector names accepts multiple spellings and languages for sector names ("Far Frontiers"/"Afachtiabr", "Dagudashaag"/"Dagudashag", etc) and is case-insensitive. Remember to URL-encode non-alphanumeric characters (e.g. spaces are %20 or +).
The Coordinates API will look up a sector/hex location and produce sector/hex coordinates suitible for further calculations. For convenience, the JumpMap API, Credits API, IFRAME API, and Permalinks all accept named locations using sector and hex parameters.
Example: Regina is "Spinward Marches" "1910"
Sector/Hex are the simplest numeric coordinates. These must be specified as a quartet of (sx, sy, hx, hy). The Core sector is at (0,0), with positive x being Trailing and positive y being Rimward. Hex coordinates are 1...32 and 1...40. Note that hx and hy must be specified separately. Developers should be aware that many languages (C/C++, JavaScript, etc) will parse numbers with leading 0's as octal, so 08 and 09 are treated as erroneous and gives bogus results. Use an appropriate parsing function with an explicit radix.
The Coordinates API will map a sector/hex name (such as "Spinward Marches", "1910") to the numeric quartet in this coordinate space. The JumpMap API and Credits API accept these coordinates using sx, sy, hx and hy parameters.
Example: Regina (Spinward Marches 1910) is (sx=-4, sy=-1, hx=19, hy=10)
World-space coordinates are more compact than Sector/Hex coordinates, requiring just two numbers. The transformation is simple, and based around Reference (Core 0140). In this scheme, Reference is at 0,0, positive x is Trailing and positive Y is Rimward. To convert Sector/Hex to world-space coordinates, simply compute the distance to Reference:
This scheme allows trivial conversions to the canonical Traveller ring/ray system, but is far more convenient given that the origin is within charted space. This coordinate system is used by the Credits API and the JumpMap API, which require selection of a specific hex. The coordinates are specified as x and y parameters
Example: Regina is (x=-110, y=-70)
While world-space coordinates make a lot of sense for describing hexes, the fractional positioning required for precisely positioning the map dictates an additional map-space coordinate system. The conversion from world-space to map-space coordinates requires two steps:
This coordinate system is used by Permalinks and the IFRAME API when a precise view point is required. The coordinates are specified as x and y parameters.
Example: Regina is (x=-95.914, y=70.5)
Coordinates used by Tile API are designed so that the basic operations of dragging the map around and requesting new tiles are as simple as possible. If the tile scale, width and height remain constant, the tiles at (0,0) and (0,1) are adjacent, and the origin is the same as map-space coordinates. Positive x is Trailing, positive y is Rimward.
NOTE: since this is effectively an image-space coordinate system, standard graphics tricks can be used. For example, to center a tile rendering on a map-space coordinate, use: x = ( map_x * scale - ( width / 2 ) ) / width and y = ( -map_y * scale - ( height / 2 ) ) / height
This coordinate system is only used by the Tile API
Example: Regina would be centered in a 512x384, 48px/pc tile at (x=-9.4919375, y=-9.3125)
<iframe src="URL" style="STYLE" frameborder="0" scrolling="no"></iframe>
Where URL is one of:
And STYLE is something like:
width: 200px; height: 200px; border: solid 1px black;
<iframe src="http://www.travellermap.com/iframe.htm?x=-95.914&y=70.5&scale=48&options=887" style="width: 200px; height: 200px; border: solid 1px black;" frameborder="0" scrolling="no"></iframe>
http://www.travellermap.com/Coordinates.aspx?sector=SECTORNAME[&hex=XXYY]
http://www.travellermap.com/Credits.aspx ?x=XCOORD&y=YCOORD |sx=SECXCOORD&sy=SECYCOORD &hx=HEXXCOORD&hy=HEXYCOORD |sector=SECTORNAME&hex=XXYY
http://www.travellermap.com/SEC.aspx?sector=SECTORNAME
http://www.travellermap.com/MSEC.aspx?sector=SECTORNAME
http://www.travellermap.com/Poster.aspx?sector=SECTORNAME[&scale=N][&subsector=X][&rotation=R][&options=O]
<img src="http://www.travellermap.com/Poster.aspx?sector=Spinward+Marches&subsector=C&options=2928&scale=48" style="border: solid 4px black;" />
http://www.travellermap.com/JumpMap.aspx?x=XCOORD&y=YCOORD|sx=SECXCOORD&sy=SECYCOORD&hx=HEXXCOORD&hy=HEXYCOORD|sector=SECTORNAME&hex=XXYY[&scale=N][&options=O]
<img src="http://www.travellermap.com/JumpMap.aspx?sector=Spinward+Marches&hex=1910&jump=4&scale=48&options=2096" />
http://www.travellermap.com/Search.aspx?q=QUERY
http://www.travellermap.com/Tile.aspx?x=XCOORD&y=YCOORD&scale=N&options=O[&w=WIDTH][&h=HEIGHT]
http://www.travellermap.com/Universe.aspx[?era=YEAR]
The script file that implements the site logic is full of goodies, such as the mechanism to convert coordinate spaces between the map's internal format and Traveller parsec numbering, and the definitions of the options that are referenced in various APIs.
Specifically, the following scripts are used: