API for querying system information and submitting distances

This is subject to change. Documentation & API written October 4th, 2016.

If you need to do some testing on our API, please use the http://beta.edsm.net:8080/ endpoint.
It is usually up to date with the production database, but if not, send us a message.

Getting information about a specific system - URL: https://www.edsm.net/api-v1/system

Getting information about several systems at once - URL: https://www.edsm.net/api-v1/systems

Retrieving distances - URL: https://www.edsm.net/api-v1/distances

Get systems in a sphere - URL: https://www.edsm.net/api-v1/sphere-systems

List all systems which are located around a position or another system. Submit a system with known coordinates via systemName=... to have this system as the center of the sphere or submit coordinates in the form x=12.34&y=5.6&z=7.89 to have a sphere around this point.
Submit the desired radius of the sphere with radius=n.nn.
Please note that the distance calculation is done by the database server and may differ slightly from the Elite: Dangerous Client ingame calculation.

Get systems in a cube - URL: https://www.edsm.net/api-v1/cube-systems

List all systems which are located around a position or another system. Submit a system with known coordinates via systemName=... to have this system as the center of the cube or submit coordinates in the form x=12.34&y=5.6&z=7.89 to have a cube around this point.
Submit the desired size of the cube with size=n.
This method is faster than the sphere method as it does not rely on heavy calculation.
Output is in JSON format. Parameters:
systemName Name of the system(s) you want information about. This is case-insensitive as ingame.
Spaces and other special characters in the system's name must be URL encoded.
If you call the API from within a browser, it should be encoded automatically.
If you are writing some 3rd party app, you probably know what to do. In PHP use urlencode.
Use the percent sign "%" for a wildcard.
coords Set to 1 if you want to get the coordinates (if known).
showId Set to 1 if you want to get our internal id.
Additionally, you can receive a mergedTo id, indicating that the current system was renamed and merge to another system.
showPermit Set to 1 if you want to see if a system require a permit to be entered. Also return the name of the permit when known.
showInformation Set to 1 if you want to get some basic information about populated systems, like government, allegiance, population...
pushed Set to 1 if you want to get only systems that are pushed on our homepage.
known Set to 1 if you want to get only systems with known coordinates.
unknown Set to 1 if you want to get only systems with unknown coordinates.
distances Set to 1 if you want to receive the submitted distances.
submitted Set to 1 if you want to receive information who and when submitted the names and distances.
includeHidden Set to 1 if you want to get systems and distances marked as "hidden".
Usually these are wrong system names or wrong distances submitted.
startDateTime
YYYY-MM-DD HH:MM:SS
If you only want to receive data for systems that were updated after a specific date & time, use this parameter.
That parameter is inclusive. All dates must be UTC.
endDateTime
YYYY-MM-DD HH:MM:SS
If you only want to receive data for systems that were updated before a specific date & time, use this parameter.
That parameter is exclusive. All dates must be UTC.
problems Set to 1 if you want to see the known errors.
One possible error is a submitted distance to another system where both coordinates are known, and the submitted distance is not the same as the calculated distance.
This is probably a CMDR's typo when submitting distances.
Another error is when more than one distance was submitted to the same reference system.
Both are problematic because they may prevent coordinate calculation, show former wrong calculations or other bad things like moved systems.
reqdists If you want to help finding new coordinates, set this to the number of systems you want to see where distances are needed. You get an array "reqlocatedists" with unknown systems.
Parameters are given in the URL to open. Add a question mark and the parameters you want, separated by an ampersand "&".

Note: Some parameters may be ignored when not useful, f.ex. distances=1 is always assumed for distances.php.
Most parameters are optional, but some may be required, f.ex. sysname must be set when calling sysinfo.php.

Submitting distances - URL: https://www.edsm.net/api-v1/submit-distances

The parameters needed for submitting distances should be the same as EDSC/TGC uses, to make it as easy as possible for others to use this API as a TGC replacement.
TornSoul's documentation can be found here.
You can use either the POST or the GET method.
fromSoftware

Name of the software used to submit the data.
If omitted or empty, software will not be set.

    {
        "data": {
            "fromSoftware": "My beautiful software",
            ...
        }
    }
fromSoftwareVersion

Version of the software used to submit the data.
If omitted or empty, software version will not be set.

    {
        "data": {
            "fromSoftwareVersion": "1.1",
            ...
        }
    }
commander

Name of the commander submitting the data.
If omitted or empty, commander name will be set to anonymous.

    {
        "data": {
            "commander": "Inhumierer",
            ...
        }
    }
p0
    {
        "data": {
            "p0": { "name": "Shudun Sector AA-A d142" },
            ...
        }
    }
refs
    {
        "data": {
            "refs": [
                { "name": "Ammapa", "dist": 121.85 },
                { "name": "Wanggu", "dist": 135.45 },
                ...
            ],
            ...
        }
    }

System, distance & coordinate return messages and message numbers

100 Base/Reference system added

The base/reference system's name from where the distances were submitted was not known to the database and has been added.

101 Base/Reference system probably non existant

The system from where the distances were submitted probably does not exist.
Most likely it was submitted before and the name is a typo or it has been removed by FD.
This system can't be used for any distance submission or coordinate calculation.

If you are very sure this system really exists in game, contact us on Elite Dangerous Forum for further investigation.
We all make errors.

102 Base system added with coordinates

The base system's coordinates were found, and it has been added to the database.

104 Base system coordinates found

Coordinates for the base system could be calculated, they have been saved.

105 Found alternative positions

Coordinates for the base system could be calculated, but there are additional grid positions close to this position. More reference distances to other systems are needed.

106 No match found

No position could be calculated, we need more referencing distances.
This may happen if there were wrong distances submitted.
In the near future the code for calculating the coordinates will probably be able to handle a few wrong distances, and hilight or even automatically hide them.

108 Need 4 references minimum

The code to calculate coordinates needs 4 (or more) referencing distances, and there are less.
An additional return value "refnum" gives the number of references in the database.
Please note that only distances to systems with known coordinates do count.

109 Coordinates not found

There was another reason which prevented coordinate calculation.
Please contact us to investigate.

110 Base system name not found in query

To be mostly compatible to EDSC the request for submitting distances needs to have a base system name. It should be encapsuled in an object with a name property, inside the p0 object.

    {
        "data": {
            "p0": { "name": "Shudun Sector AA-A d142" },
            ...
        }
    }
195 Unknown error processing query

We could not find the GET/POST query.
If that happens, make sure you use one the method.

196 Could not find the data object in query

We could not find the data object in query.
To avoid that error, make sure your query contains an object with a data property.

    {
        "data": {
            ...
        }
    }
197 JSON decoding failed

Your JSON string is malformed.
Use JSONLint to test it.

 
200 Distance saved

The submitted distance was saved.

201 Not a number

The submitted distance is not a number and can't be processed.

202 Distance exists, CR saved

The submitted distance already exists in the database, the additional confidence for verifying was saved.

203 Distance exists, CR increased

The submitted distance already exists in the database, and it was submitted by the same CMDR.
The confidence vor verifying was increased.

204 Not saved, base system and reference system already have locked coordinates

The submitted distance was not saved because both the base system and the reference system coordinates are already locked.

 
300 Coordinates found

The coordinates for the system could be calculated and saved.

305 Found alternative positions

See #105

306 No match found

See #106

308 Need 4 references minimum

See #108

309 Coordinates not found

See #109

310 System send to our background process

To avoid timeout on the distances submission, references systems are pulled to our background process to check if coordinates can be found.

When combining parameters to ask for system names, coordinates and required things, think about useful combinations. If you require a complete list of systems and distances, this will get quite huge.
The server compresses the answer if you accept GZIP encoding, so the transfer won't take too long, but it will still be a list of approx. 44.000 systems and 170.000 distances, as of end May 2015.
If you set "reqdists" to 10, you'll get 880.000 system names and 440.000 distances additionally.
Besides that the computing of required references takes some time, so you'll probably have to wait some time to get the answer.

Retrieving "hidden" systems and distances

Experience and time have shown that it is better to keep wrong distances, system typos etc. in the database but mark them for not being used for any normal display, distance calculation and similar.
If you want to receive JSON arrays containing the hidden distances and systems, call:
The system names and distances found here are most probably wrong and do not match the ingame galaxy map.
If you find any which are OK in game here, please let me know.