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@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.
JSONP - How to use this site's data APIs in your Web pages
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
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 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
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:
-
Account for "odd" hexes being further corward than "even" hexes - i.e. hex 1910 is further coreward than hex 2010.
Also note that odd/even switch places between Sector/Hex and World-space since Reference is at 0140 and (0,0) respectively.
-
Account for hexes being packed more tightly horizontally than vertically, at a ratio of cos(30°):1 (h:v), and the
y axis is inverted. (This is the only coordinate system with an inverted Y axis. I can't explain that;
I must have been asleep at the keyboard.)
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)