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.

Many APIs take x and y coordinate parameters. The coordinate system for those values varies depending on the API. See the Coordinate Systems documentation for more details.

Contents

Functional APIs vs. Semantic Data URLs

The site exposes the same functions through two different URL schemes. For example, to render a poster-style map of Deneb you can use either of these URLs:

http://travellermap.com/api/poster?sector=Deneb

http://travellermap.com/data/Deneb/image

The first URL is structured based on the function that is being performed, and takes parameters (defining data to operate on) and options (that refine the behavior); these URLs start with a /api/ prefix. The second URL is structured around the object being operated on, then specifies the data to retrieve; these URLs start with a /data/ prefix.

In this case, both URLs expose identical functionality. Not all functions exposed by the first ("api") form have a corresponding second ("data") form – for example, rendering arbitrary rectangles of space, or selecting a sector by x/y coordinates. On the other hand, the data URLs are much easier to remember and share. Both will be supported indefinitely.

Semantic URL Namespace

Rendering Options and Styles – visual appearance of the map

All of the APIs that produce images (Poster, Jump Map, Tile) as well as the site itself (including IFRAME) take an options parameter that is a bit field 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.

Tip: You can use the checkboxes in the table below to compute an options value. Reload the page to see the default options.

OptionHexadecimalDecimalNotes
SectorGrid 0x0001 1 Show sector grid.
SubsectorGrid 0x0002 2 Show subsector grid.
SectorsSelected 0x0004 4 At low scales, show only some sector names
SectorsAll 0x0008 8 Show all sector names
BordersMajor 0x0010 16 Show major region borders.
BordersMinor 0x0020 32 Show minor region borders.
NamesMajor 0x0040 64 Show major region names.
NamesMinor 0x0080 128 Show minor region names.
WorldsCapitals 0x0100 256 Show important worlds (capitals).
WorldsHomeworlds 0x0200 512 Show important worlds (homeworlds).
ForceHexes 0x2000 8192 Never render square hexes.
WorldColors 0x4000 16384 Use additional world colors for atm/hyd.
FilledBorders 0x8000 32768 Background colors for bordered regions.

Computed options value: (try it)

Some flag values (not listed in the above table) have been deprecated. See the source code for more details. Because URLs may exist that reference them the flags cannot be reused. Going forward, distinct query parameters will be used to control rendering options. In addition, the flags do not correspond 1:1 to options shown on the main map page as the as the UI has evolved and simplified over time. Specifically, the pairs SectorGrid/SubsectorGrid, BordersMajor/BordersMinor, NamesMajor/NamesMinor, and WorldsCapitals/WorldsHomeworlds are always set/cleared together by one checkbox.

Behind the scenes, options values are one input to a style calculation; other inputs include the scale (see below). The options flags (e.g. SectorGrid) only apply at certain scales, per the following table:

Feature 132 116 18 14 12 1 2 4 8 16 32 64 128
Galaxy
Local Rifts
Random Star Field
Important Worlds
Worlds
Worlds (Basic)
Worlds (Full Data)
Worlds (UWP)
Sector Grid
Subsector Grid
Sector Names
Subsector Names
Parsecs (Square)
Parsecs (Hex)
Labels (Macro)
Labels (Micro)
Borders (Macro)
Borders (Micro)
Routes (Macro)
Routes (Micro)

Styles

Style values include:

poster example 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 exampleprint
A color-on-white style best suited for color printing.
atlas exampleatlas
A grayscale black-on-white style that matches the visual style of the Atlas of the Imperium and early supplements, best for black-and-white printing.
candy examplecandy
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.

Page and API

These options are available when calling rendering APIs, the main page, and IFRAME API.

routes=0
Routes are not rendered (macro-scale or micro-scale)
dimunofficial=1
At scales where worlds are shown (dotmap or more), sectors with unofficial data will be dimmed

API Only

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)
allhexes=1
All hexes are numbered. The default is just to number hexes with worlds.
dpr=number
The image is rendered for the specified device pixel ratio. For example, specifying dpr=2 would produce an image at double the resolution, providing better quality for iOS "retina" and other high-density displays.
datauri=1
The image is returned as a base64-encoded Data URI rather than as binary data. This is useful when requesting images via POST via XHR to insert into HTML.

IFRAME Only

These options are available only when the IFRAME API is used.

forceui=1
The page UI (search box, options buttons, etc) is shown. The default is to hide the UI when the map is embedded in another page. Note that not all options may make sense.

HTML APIs

Query Parameters – Main Page

Options:

scale
scale in pixels/parsec (default is 64)
options
rendering options
style
rendering style
sector
hex
specify a location in named coordinateshex is optional; scale will be ignored.
sx
sy
hx
hy
specify a location in Sector/Hex coordinates (scale must also be explicitly specified)
x
y
specify a location in Map-space coordinates
galdir=0
Turn off the overlay of galactic directions (Spinward, Coreward, etc)

Beta Features:

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

yah_sector
yah_hex
Named coordinates to place a "You Are Here" graphical marker. (example)
yah_sx
yah_sy
yah_hx
yah_hy
Sector/Hex coordinates to place a "You Are Here" graphical marker. (example)
marker_sector
marker_hex
marker_url
Named coordinates and image URL for a custom marker. The image should be a 256px × 256px PNG and will be centered on the given coordinates. (example)
ox
oy
ow
oh
Map-space coordinates for the left, top, width, and height of an overlay or highlight rectangle to place over the map.To specify additional overlay rectangles, include ox1 (etc) for the first additional overlay, ox2 (etc) for the second additional overlay, and so on. For example, here's the Atlas of the Imperium coverage area.
A handful of example markers are available; relative URLs can be used for these. Images by Andrew Boulton, c/o FFE.
Beowulf-Class Free Trader res/markers/beowulf.png
Sulieman-Class Scout/Courier res/markers/scout.png
Empress Marava-Class Far Trader res/markers/fartrader.png
Akkigish-class Subsidized Merchant res/markers/submerchant.png

Go Links – short URLs for specifying a location on the map

API URLs:

http://travellermap.com/go/sector

http://travellermap.com/go/sector/hex

These URLs navigate the map page, and can be used instead of the longer ?sector=sector&hex=hex syntax.

Example:

IFRAME – embed a map in your page

Usage:

<iframe src="URL" style="STYLE"></iframe>

Where URL is any main page URL, including query parameters and/or go links.

And STYLE is something like:

width: 200px; height: 200px; border: solid 1px black;

Notes:

  • You use the same URL as for the main page. The site detects that it's running in an iframe and automatically hides the UI.
  • User preferences are ignored, so that you can control the styling and location with parameters.
  • You can drag with the mouse and zoom by using the mouse wheel or double-clicking (hold Alt and double-click to zoom out). You can even use the IJKL keys or arrow keys to scroll the map.
  • For sites such as Wikis that (for security reasons) do not allow embedding arbitrary IFRAMEs, see the Poster API instead.
  • The STYLE of the IFRAME element can be anything you want to match your site – the width and height are just examples
  • By default, the UI is hidden. To force the UI to be shown in an iframe, add the URL parameter forceui=1

Example:

<iframe
   src="http://travellermap.com/go/spin/1910?style=print"
   style="width: 400px; height: 200px; border: ridge 10px gray;">
</iframe>
    

Data APIs

Coordinates – sector lookup and coordinate conversion

API URLs:

http://travellermap.com/api/coordinates?sector=sector

http://travellermap.com/api/coordinates?sector=sector&hex=hex

http://travellermap.com/api/coordinates?sx=sx&sy=sy

http://travellermap.com/api/coordinates?sx=sx&sy=sy&hx=hx&hy=hy

Data URLs:

http://travellermap.com/data/sector/coordinates

http://travellermap.com/data/sector/hex/coordinates

Parameters:

sector
specify the sector location by name, e.g. "Spinward%20Marches"
hex
specify hex location within the named sector
sx
sy
sector in sector/hex-space coordinates
hx
hy
hex in sector/hex-space coordinates

Notes:

  • The following coordinates are returned:
  • The default output format is JSON. To retrieve results in XML form, specify the HTTP header Accept: text/xml or include accept=text/xml in the query string.

Example:

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

API URLs:

http://travellermap.com/api/credits?sector=sector

http://travellermap.com/api/credits?sector=sector&hex=hex

http://travellermap.com/api/credits?sx=sx&sy=sy

http://travellermap.com/api/credits?sx=sx&sy=sy&hx=hx&hy=hy

http://travellermap.com/api/credits?x=x&y=y

Data URLs:

http://travellermap.com/data/sector/credits

http://travellermap.com/data/sector/hex/credits

Parameters:

sector
specify the sector location by name, e.g. "Spinward%20Marches"
hex
specify hex location within the named sector (defaults to 1620 if unspecified)
sx
sy
sector in sector/hex-space coordinates
hx
hy
hex in sector/hex-space coordinates
x
y
location in world-space coordinates

Notes:

  • The default output format is JSON. To retrieve results in XML form, specify the HTTP header Accept: text/xml or include accept=text/xml in the query string.

Example:

SEC – retrieve UWP data for a sector

HTTP Methods:

GET
The sector to output is specified some combination of the following URL parameters:

API URLs:

http://travellermap.com/api/sec?sector=sector

http://travellermap.com/api/sec?sector=sector&hex=hex

http://travellermap.com/api/sec?sector=sector&subsector=subsector

http://travellermap.com/api/sec?sector=sector&quadrant=quadrant

http://travellermap.com/api/sec?sx=sx&sy=sy

Data URLs:

http://travellermap.com/data/sector

http://travellermap.com/data/sector/sec

http://travellermap.com/data/sector/tab

http://travellermap.com/data/sector/subsector

http://travellermap.com/data/sector/subsector/sec

http://travellermap.com/data/sector/subsector/tab

http://travellermap.com/data/sector/quadrant

http://travellermap.com/data/sector/quadrant/sec

http://travellermap.com/data/sector/quadrant/tab

Parameters:

sector
sector name or T5SS abbreviation
subsector
AP or name; optional – if specified , only UWPs for that subsector will be included
quadrant
one of Alpha, Beta, Gamma or Delta
sx
sy
sector in sector/hex-space coordinates
POST
The body of the request is sector data to be parsed. After successful parsing, the same data is returned but reformatted according to the selected options. This can be used to convert SEC data to T5 Tab Delimited for easier parsing by script. The format of the input data is "sniffed" – if it contains tabs it is assumed to be in T5 Tab Delimited format; if it contains extension field delimiters it is assumed to be in T5 Column Delimited format; otherwise, it is parsed as Legacy SEC format.

Parameters:

lint=1
Return an HTTP failure (400) if warnings or errors are found while parsing the sector data. The default is to silently ignore any lines with errors.

Options:

type=SecondSurvey
Data Format Definition The Traveller5 Second Survey format in human readable form: Hex, Name, UWP, Trade Classifications and Remarks, Extensions (Ix, Ex, Cx), Nobility (N), Bases (B), Travel Zone (Z), PBG, Worlds (W), Allegiance and Stellar. Note that fields may be blank if no official T5 data exists.

Second Survey is the default for /data/ URLs.

type=TabDelimited
Data Format Definition Full Traveller5 Second Survey data, in a more easily parsed format.
type=Legacy
Data Format Definition Legacy sector format: Name, Hex, UWP, Bases, Trade Classifications and Remarks, Travel Zone, PBG, Allegiance and Stellar.

Legacy format is the default for /api/ URLs

metadata=0
Don't include sector metadata as comments in the file
header=0
Don't include field definitions in the file
sscoords=1
Use subsector style (0101-0810) numbering instead of sector style (0101-3240)

Notes:

  • The column widths in SecondSurvey format are computed dynamically. The header and separator lines must be parsed to identify columns.
  • The column widths in the legacy format are defined in the header; data may be truncated to fit.
  • If you are programatically consuming the data, it is strongly recommended that you use TabDelimited format
  • If a jsonp query parameter is specified, the results are wrapped in a JSONP callback

Example:

Metadata – retrieve metadata for a sector

HTTP Methods:

GET
The sector to output is specified some combination of the following URL parameters:

API URLs:

http://travellermap.com/api/metadata?sector=sector

http://travellermap.com/api/metadata?sx=sx&sy=sy

Data URLs:

http://travellermap.com/data/sector/metadata

Parameters:

sector
sector name or T5SS abbreviation
sx
sy
sector in sector/hex-space coordinates
POST
The body of the request is sector metadata to be parsed. After successful parsing, the same data is returned but reformatted according to the selected options. This can be used to convert XML or MSEC to JSON for easier parsing by script. The input data format is "sniffed" – if it has an XML prologue it is assumed to be XML format (example); otherwise, MSEC format (example) is assumed. JSON parsing is not supported.

Parameters:

lint=1
Return an HTTP failure (400) if warnings or errors are found while parsing the sector data. The default is to silently ignore any lines with errors.

Notes:

  • The default output format is JSON. To retrieve results in XML form, specify the HTTP header Accept: text/xml or include accept=text/xml in the query string.
  • The XML data is the same format as consumed by the Poster API when using HTTP POST.

Example:

MSEC – generate sec2pdf compatible metadata for a sector

API URLs:

http://travellermap.com/api/msec?sector=sector

http://travellermap.com/api/msec?sx=sx&sy=sy

Data URLs:

http://travellermap.com/data/sector/msec

Parameters:

sector
sector name
sx
sy
sector in sector/hex-space coordinates

Notes:

Example:

Jump Worlds – return a list of worlds within Jump-N from some location

API URLs:

http://travellermap.com/api/jumpworlds?x=x&y=y

http://travellermap.com/api/jumpworlds?sx=sx&sy=sy&hx=hx&hy=hy

http://travellermap.com/api/jumpworlds?sector=sector&hex=hex

Data URLs:

http://travellermap.com/data/sector/hex

http://travellermap.com/data/sector/hex/jump/jump

Parameters:

jump
jump distance to include (0 through 12, default is 6)
sector
specify the sector location by name, e.g. "Spinward%20Marches"
hex
specify hex location within the named sector
sx
sy
sector in sector/hex-space coordinates
hx
hy
hex in sector/hex-space coordinates
x
y
location in world-space coordinates

Notes:

  • The short Data URL form (/data/sector/hex) is an alias for jump 0 - only details for the specified system are returned.
  • Returns a list of worlds. Each world has the following fields (in no particular order), although fields may be omitted if blank:
    • Name
    • Hex
    • UWP
    • Bases
    • Remarks
    • Zone
    • PBG
    • Allegiance
    • Stellar
    • Ix
    • Ex
    • Cx
    • Nobility
    • Worlds
  • The default output format is JSON. To retrieve results in XML form, specify the HTTP header Accept: text/xml or include accept=text/xml in the query string.

Example:

Worlds within Jump-4 of Regina

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

API URLs:

http://travellermap.com/api/universe

Data URLs:

http://travellermap.com/data

Options:

era
year, e.g. 0, 1110, 1248
requireData
if 1, only sectors with data files will be included

Notes:

  • Returns a list of sectors providing X,Y coordinates and names.
  • The era parameter filters on an exact match only; the tagging of sectors with a precise year is sparse
  • The default output format is JSON. To retrieve results in XML form, specify the HTTP header Accept: text/xml or include accept=text/xml in the query string.

Example:

Rendering APIs

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

API URLs:

http://travellermap.com/api/tile?x=x&y=y&scale=N

Parameters:

x
y
tile-space coordinate
scale
scale in pixels/parsec

Options:

options
rendering options
style
rendering style
w
width of image to generate (pixels, default 256)
h
height of image to generate (pixels, default 256)
accept
specify application/pdf for PDF output; otherwise output depends on options

Notes:

  • Generate a PNG or JPEG image of the specified region.
  • Coordinates are in tile-space coordinates (optimized for tile rendering, not navigation); conversion functions are in the script
  • Bitmap image format depends on selected options ("Candy" produces JPEG, otherwise PNG)
  • The HTTP Accept header can be used to specify application/pdf instead of the query parameter.

Example:

Poster – render an image of a sector, quadrant or subsector

API URLs:

http://travellermap.com/api/poster

http://travellermap.com/api/poster?sector=sector

http://travellermap.com/api/poster?sector=sector&subsector=subsector

http://travellermap.com/api/poster?sector=sector&quadrant=quadrant

Data URLs:

http://travellermap.com/data/sector/image

http://travellermap.com/data/sector/subsector/image

http://travellermap.com/data/sector/quadrant/image

HTTP Methods:

GET
The content to render is specified some combination of the following URL parameters:

Parameters:

sector
sector name
quadrant
one of Alpha, Beta, Gamma or Delta
subsector
subsector index (AP or name)
domain
one of the domains of the Third Imperium (Sylea, Vland, Gateway, Ilelish, Antares, Sol, Deneb)
x1
y1
top-left hex (inclusive) of the rectangle in World-Space Coordinates
x2
y2
bottom-right hex (inclusive) of the rectangle in World-Space Coordinates
POST
The content to render is submitted as part of the payload, allowing custom maps to be rendered. Options (see below) can be specified either as URL parameters or in the POST body. A specific subsector can be rendered using this parameter, which can be either part of the POST data or a URL parameter:

Parameters:

subsector
subsector index (AP)
lint=1
Return an HTTP failure (400) if warnings or errors are found while parsing the sector data. The default is to silently ignore any lines with errors.
Sector data and metadata can be sent in a variety of different ways, determined by the Content-Type header:
application/x-www-form-urlencoded
This is a standard HTML form formatted body. In the POST body, a field named data must contain the sector data and a field named metadata may contain the metadata.
multipart/form-data
This allows file attachments to be used, as produced by using an HTML form with input type="file" elements. An attachment named file must contain the sector data, and an attachment named metadata may contain the metadata.
text/plain
The body of the request is the sector data. No metadata can be specified using this type. Other options must be specified in the URL.
Sector data must be specified in SEC (example), T5 Tab Delimited (example), or T5 Column Delimited (example) format. Metadata must be specified in either XML (example) or MSEC (example) format.

Options:

scale
scale in pixels/parsec (default is 64)
rotation
rotate the image, 1 for 90° clockwise, 2 for 180°, 3 for 90° counterclockwise
options
rendering options
style
rendering style
accept
specify application/pdf for PDF output
thumb
specify 1 to render a thumbnail (16 pixels/parsec)

Notes:

  • Generate a PNG or JPEG image of the specified sector (or just subsector), or an arbitrary rectangle of space.
  • Image format depends on selected options ("Candy" produces JPEG, otherwise PNG)
  • The HTTP Accept header can be used to specify application/pdf instead of the query parameter.
  • The Poster Maker provides a friendly user interface to this API.

Example:

<img src="http://travellermap.com/api/poster?sector=spin&subsector=C&style=atlas&scale=48">

Regina Subsector

Jump Map – render an image of hexes within Jump-N of some location

API URLs:

http://travellermap.com/api/jumpmap?sector=sector&hex=hex&jump=jump

http://travellermap.com/api/jumpmap?sx=sx&sy=sy&hx=hx&hy=hy&jump=jump

http://travellermap.com/api/jumpmap?x=x&y=y&jump=jump

Data URLs:

http://travellermap.com/data/sector/hex/jump/jump/image

HTTP Methods:

GET
The map to render is specified some combination of the following URL parameters:

Parameters:

jump
jump distance to render (0 through 12, default is 6)
sector
specify the sector location by name, e.g. "Spinward%20Marches"
hex
specify hex location within the named sector
sx
sy
sector in sector/hex-space coordinates
hx
hy
hex in sector/hex-space coordinates
x
y
location in world-space coordinates
POST
The content to render is submitted as part of the payload, allowing custom maps to be rendered. Options (see below) can be specified either as URL parameters or in the POST body. The specific hex to render is specified using these paramters, which can be either part of the POST data or URL parameters:

Parameters:

jump
jump distance to render (1 through 12, default is 6)
hex
specify hex location within the named sector
lint=1
Return an HTTP failure (400) if warnings or errors are found while parsing the sector data. The default is to silently ignore any lines with errors.
Sector data and metadata can be sent in a variety of different ways, determined by the Content-Type header:
application/x-www-form-urlencoded
This is a standard HTML form formatted body. In the POST body, a field named data must contain the sector data and a field named metadata may contain the metadata.
multipart/form-data
This allows file attachments to be used, as produced by using an HTML form with input type="file" elements. An attachment named file must contain the sector data, and an attachment named metadata may contain the metadata.
text/plain
The body of the request is the sector data. No metadata can be specified using this type. Other options must be specified in the URL.
Sector data must be specified in SEC (example), T5 Tab Delimited (example), or T5 Column Delimited (example) format. Metadata must be specified in either XML (example) or MSEC (example) format.

Options:

scale
scale in pixels/parsec (default is 64)
options
rendering options
style
rendering style
border
whether or not to render a thick border; specify 1 (yes, the default) or 0 (no)
accept
specify application/pdf for PDF output

Notes:

  • Generate a PNG image of the specified region.
  • PNG images (indexed, 8-bits per pixel) are returned unless PDF is requested; areas outside the hex borders will be transparent.
  • The HTTP Accept header can be used to specify application/pdf instead of the query parameter.
  • The Poster Maker provides a friendly user interface to this API.

Example:

<img src="http://travellermap.com/api/jumpmap?sector=spin&hex=1910&jump=4&scale=48&style=atlas">

Regina Jump-4 Map

Appendix

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).

Sectors mapped as part of the Traveller5 Second Survey (T5SS) process can be referenced by abbreviation as well, where the abbreviation is the first 4 letters (e.g. "spin" for the Spinward Marches), or 3 in the case of Ley Sector ("ley");

The Coordinates API will look up a sector/hex location and produce sector/hex coordinates suitible for further calculations. For convenience, the Jump Map 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 give unexpected results. Use an appropriate parsing function with an explicit radix.

The Coordinates API will map a sector / hex pair sector/hex name (such as "Spinward Marches", "1910") to the numeric quartet in this coordinate space. The Jump Map 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:

var ReferenceSectorX = 0;
var ReferenceSectorY = 0;
var ReferenceHexX = 1;
var ReferenceHexY = 40;
var SectorWidth = 32;
var SectorHeight = 40;

function SectorHexToXY(sx, sy, hx, hy) {
  var x = ( ( sx - ReferenceSectorX ) * SectorWidth ) + ( hx - ReferenceHexX );
  var y = ( ( sy - ReferenceSectorY ) * SectorHeight ) + ( hy - ReferenceHexY );
  return {x: x, y: y};
}
  

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 Jump Map API, which require selection of a specific hex. The coordinates are specified as x and y parameters

The Coordinates API will map a named location (sector, hex) or sector/hex coordinates (sx, sy, hx, hy) to world-space coordinates.

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

Within Charted Space, to convert world-space coordinates to ring/ray:

ring = y + 10000
ray = x if x ≥ 0, or x + 62833 otherwise

Example: Regina is (-70 + 10000) ring/ray (-110 + 62833), or 9930 ring/ray 62723

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 coreward 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, and the y axis is inverted.

    This is the only coordinate system with an inverted Y axis. I don't know what I was thinking. I must have been asleep at the keyboard.

function isEven(n) { return (n % 2) === 0; }
var ParsecScaleX = Math.cos(Math.PI / 6); // cosine 30°
var ParsecScaleY = 1;

function worldXYToImageXY(world_x, world_y) {
  var ix = world_x - 0.5
  var iy = isEven(world_x) ? world_y - 0.5 : world_y
  var x = ix * ParsecScaleX;
  var y = iy * -ParsecScaleY;
  return {x: x, y: y};
}
  

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;
  

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_center_x * scale - ( width / 2 ) ) / width;
y = ( -map_center_y * scale - ( height / 2 ) ) / height;
  

This coordinate system is only used by the Tile API. The coordinates are specified as x and y parameters.

Example: Regina would be centered in a 512x384, 48px/pc tile at (x=-9.4919375, y=-9.3125)

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

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).

For example, here's how you could implement a search function on your site:

// Call this function with a search query:
function jsonp_example(q) {
  var url = 'http://travellermap.com' +
            '/api/search?q=' + encodeURIComponent(q) + '&jsonp=cbfn';
  var script_tag = document.createElement('script');
  script_tag.setAttribute('src', url);
  document.body.appendChild(script_tag);
}

// This function is called automatically with the results:
function cbfn(data) {
  window.alert('Callback, got ' + data.Results.Count + ' results.');
}
  

Example:

Make a JSONP call

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:

The Traveller game in all forms is owned by Far Future Enterprises. Copyright © 1977 – 2014 Far Future Enterprises. Fair Use Policy

Fork me on GitHub