The Traveller Map API

Overview

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@gmail.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.

Contents

Rendering Options and Styles - visual appearance of the map

All of the APIs that produce images (Poster, JumpMap, Tile) as well as the site itself (including IFRAME) take an options parameter that is a bit-map of rendering style options and a style parameter that names a visual style/color scheme for the map.

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.

OptionHexadecimalDecimalNotes
SectorGrid 0x0001 1
SubsectorGrid 0x0002 2
SectorsSelected 0x0004 4At low scales, show only some sector names
SectorsAll 0x0008 8Show all sector names
BordersMajor 0x0010 16
BordersMinor 0x0020 32No longer used
NamesMajor 0x0040 64
NamesMinor 0x0080 128No longer used
WorldsCapitals 0x0100 256
WorldsHomeworlds 0x0200 512
RoutesSelected 0x0400 1024No longer used
PrintStyle 0x0800 2048No longer used
CandyStyle 0x1000 4096No longer used
ForceHexes 0x2000 8192Beta Feature
WorldColors 0x4000 16384Beta Feature
FilledBorders 0x8000 32768Beta Feature

Styles

Style values include:

poster
A color-on-black style that matches the "Spinward Marches" poster included with the Deluxe Traveller boxed set and the Imperium Map poster. This is the default.
print
A color-on-white style best suited for color printing.
atlas
A grayscale black-on-white style that matches the visual style of the Atlas of the Imperium and early supplements.
candy
A style designed by Wayne Peters that evokes interactive map displays from contemporary movies. Does not show world base or allegiance information, but does illustrate world size and hydrographics.

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 and style parameters from the URL.

Other

These options are available when calling rendering APIs, but not the main page or IFRAME API.

sscoords=1
Hexes are numbered subsector style (0101-0810) instead of sector style (0101-3240)
routes=0
Routes are not rendered (macro-scale or micro-scale)

JSONP - How to use this site's data APIs in your Web pages

NOTE: APIs on this site output CORS headers so if you know your users will be accessing your site using reasonably up-to-date browsers you can call the APIs directly via XMLHttpRequest rather than using JSONP trick described below.

Web browsers enforce a Same Origin Policy on content, to stop a page on evilhacker.com from scripting access to your bank account with your stored credentials. This is a good thing! Unfortunately, it also means that sites that want to cooperate have to jump through some hurdles. For example, you can't have a web page on your site that calls directly into one of the APIs on this site (via XMLHttpRequest) from JavaScript. Either the the sites need to have server-to-server communication (which is troublesome to set up, impractical in some circumstances, and introduces its own security issues) or they can play some tricks. JSONP is one of those tricks.

Web browsers allow pages to dynamically add content via script. They can even add references to additional script files, and those files can come from different sites. While a script cannot make AJAX calls to another site to retrieve data, it can cause a script from that site to be loaded just like a local script. The loaded script doesn't have any special abilities - it's still running within the domain of the page. The trick is to request a script with dynamically generated content - the data you wanted to request from the remote site in the first place!

The following APIs on this site support JSONP requests:

To get a JSONP response, append &jsonp=callbackfn to your query string, where callbackfn is the name of the function you'd like the script to call. This is a function that should be pre-existing in your page, that takes an argument. The argument is the JavaScript value (usually an object with properties, sub-objects, arrays, etc).

Here's how you'd have your page make one of these requests

    function jsonp_example(q)
    {
        // This is the function you call to make the JSONP request,
        // for example when the user clicks a link
        var url = 'http://www.travellermap.com/Search.aspx' +
            '?q=' + encodeURIComponent(q) +
            '&jsonp=cbfn';
        var script_tag = document.createElement('script');
        script_tag.setAttribute('src',url);
        document.body.appendChild(script_tag);
    }                
    function cbfn(data) 
    { 
        // This is called automatically with the results
        window.alert('Callback, got ' + data.Results.Count + ' results.'); 
    }

Example:

Make a JSONP call

Coordinate Systems - the varied esoteric x/y values

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.

Named Location

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 Coordinates

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. The Coordinates API can also accept these coordinates using those parameters to map to World-Space coordinates.

Example: Regina (Spinward Marches 1910) is (sx=-4, sy=-1, hx=19, hy=10)

World-Space Coordinates

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:

x = ( ( sx - ReferenceSectorX ) * SectorWidth ) + ( hx - ReferenceHexX )
  = ( ( sx - 0 ) * 32 ) + ( hx - 1 )
  = ( sx * 32 ) + hx - 1
y = ( ( sy - ReferenceSectorY ) * SectorHeight ) + ( hy - ReferenceHexY )
  = ( ( sy - 0 ) * 40 ) + ( hy - 40 )
  = ( sy * 40 ) + hy - 40

This scheme is roughly comparable 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

The Coordinates API will map a sector name (such as "Spinward Marches") with optional hex (e.g. "1910"), or Sector/Hex coordinates (sx, sy, hx, hy) to world-space coordinates.

Example: Regina is (x=-110, y=-70)

Map-Space Coordinates

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:

ix = ( world_x - 0.5 ) *
iy = world_y - 0.5 // if world_x is even
iy = world_y       // otherwise

x = ix * ParsecScaleX
  = ix * Math.cos(Math.PI/6) // cos(30°)
y = iy * -ParsecScaleY
  = iy * -1.0
  = -iy

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)

Tile-Space Coordinates

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.

x =  map_x * scale / width
y = -map_y * scale / height

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 - embed a map in your page

Usage:

<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;

Beta Features:

Beta API features may be revoked or changed at any time, but I'll post updates to the blog first.

Notes:

Example:

<iframe src="http://www.travellermap.com/iframe.htm?x=-95.914&y=70.5&scale=48&options=887&style=poster" style="width: 200px; height: 200px; border: solid 1px black;" frameborder="0" scrolling="no"></iframe>

Coordinates - sector lookup and coordinate conversion

Usage:

http://www.travellermap.com/Coordinates.aspx?sector=SECTORNAME[&hex=XXYY]

http://www.travellermap.com/Coordinates.aspx?sx=SECXCOORD&sy=SECYCOORD[&hx=HEXXCOORD&hy=HEXYCOORD]

Parameters:

Notes:

Example:

example

Credits - get world data and metadata (attributions, etc) for a given location

Usage:

http://www.travellermap.com/Credits.aspx?x=XCOORD&y=YCOORD

http://www.travellermap.com/Credits.aspx?sx=SECXCOORD&sy=SECYCOORD&hx=HEXXCOORD&hy=HEXYCOORD

http://www.travellermap.com/Credits.aspx?sector=SECTORNAME&hex=XXYY

Parameters:

Notes:

Example:

example

SEC - output a data file for a sector

Usage:

http://www.travellermap.com/SEC.aspx?sector=SECTORNAME

http://www.travellermap.com/SEC.aspx?sx=SECXCOORD&sy=SECYCOORD

Parameters:

Notes:

Example:

example

SectorMetaData - generate metadata for a sector

Usage:

http://www.travellermap.com/SectorMetaData.aspx?sector=SECTORNAME

Parameters:

Notes:

Example:

example

MSEC - generate sec2pdf compatible metadata for a sector

Usage:

http://www.travellermap.com/MSEC.aspx?sector=SECTORNAME

Parameters:

Notes:

Example:

example

Poster - render an image of a sector or subsector

Usage:

http://www.travellermap.com/Poster.aspx?sector=SECTORNAME[&subsector=X][&scale=N][&rotation=R][&options=O][&sscoords=1]

http://www.travellermap.com/Poster.aspx?sector=SECTORNAME[&x1=N][&y1=N][&x2=N][&y2=N][&scale=N][&subsector=X][&rotation=R][&options=O][&sscoords=1]

Parameters (sector/subsector):

Parameters (arbitrary rectangle):

Parameters (common, optional):

Notes:

Example:

<img src="http://www.travellermap.com/Poster.aspx?sector=Spinward+Marches&subsector=C&options=2928&scale=48" style="border: solid 4px black;" />

Regina Subsector

JumpMap - render an image of hexes within Jump-N of some location

Usage:

http://www.travellermap.com/JumpMap.aspx?x=XCOORD&y=YCOORD[&scale=N][&options=O][&border=0]

http://www.travellermap.com/JumpMap.aspx?sx=SECXCOORD&sy=SECYCOORD&hx=HEXXCOORD&hy=HEXYCOORD[&scale=N][&options=O][&border=0]

http://www.travellermap.com/JumpMap.aspx?sector=SECTORNAME&hex=XXYY[&scale=N][&options=O][&border=0]

Parameters:

Notes:

Example:

<img src="http://www.travellermap.com/JumpMap.aspx?sector=Spinward+Marches&hex=1910&jump=4&scale=48&options=2096" />

Regina Jump-4 Map

JumpWorlds - return a list of worlds within Jump-N from some location [Beta]

Usage:

http://www.travellermap.com/JumpWorlds.aspx?x=XCOORD&y=YCOORD

http://www.travellermap.com/JumpWorlds.aspx?sx=SECXCOORD&sy=SECYCOORD&hx=HEXXCOORD&hy=HEXYCOORD

http://www.travellermap.com/JumpWorlds.aspx?sector=SECTORNAME&hex=XXYY

Parameters:

Notes:

Example:

Worlds within Jump-4 of Regina

Search - find worlds, subsectors or sectors by name (or UWP) using free text search

Usage:

http://www.travellermap.com/Search.aspx?q=QUERY

Parameters:

Notes:

Example:

example

Tile - render an image of an arbitrary rectangle of space at any size and scale

Usage:

http://www.travellermap.com/Tile.aspx?x=XCOORD&y=YCOORD&scale=N&options=O[&w=WIDTH][&h=HEIGHT]

Parameters:

Notes:

Example:

example

Universe - return a list of all sectors, optionally filtered by era

Usage:

http://www.travellermap.com/Universe.aspx[?era=YEAR]

Parameters:

Notes:

Example:

example

Script - dig into the brains of the site itself

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: