Inara API - developer guide | Elite:Dangerous

Inara API is a way how to update, send or get stuff from/to Inara. Its goal is to provide an easy method how to update your stuff here on Inara or get some data, not to provide a general 'data relay' for all Elite stuff. It was created to be as easy and understandable as possible, but it requires some development skills. If you don't know what it is about, this page of API details is probably not for you and just use any of the released apps instead, listed on the API main page. In other words - the following lines are for developers only. ;)

Inara API and its events are not intended to be one-to-one copy of the journals generated by the game or anything else, so in some cases you will need to properly handle (multiple) journal events before sending it to Inara API. It was made that way to ensure future enhanceability and independence on the journal or Frontier's companion API (cAPI) changes and improvements.

Before you provide your app to users, please be sure everything is working correctly, without any errors and you are not sending any game beta data, it is your own responsibility. Feel free to create an additional account on Inara for development and testing purposes. But, of course, if you find any bugs in the Inara API, please let me know. Also, please, let me know your app name/identifier you will be using, as it needs to be white-listed first. It is not meant to exclude anyone from using Inara API, rather a way how to identify possible problems and also to provide users a list of applications they may use.

Please send me the following:

Your application name, exactly as it will be send in the requests.
What your application generally does/will do, what you are trying to achieve with it (purely for my information).
Short application description (will be used in the list for Inara users).
URL address/homepage of your application where it can be downloaded (if any).

What to do (or not)

Although I do not want to make things too restrictive, there are some recommendations/rules. I really do not want to have my server hamsters hammered down to death by tons of requests on materials pickups and so on. ;)
The main simple rule is just: "be polite!". If you do not need to have an immediate response or you are sending a stuff that doesn't need to be updated immediately, use the event batching and limit number of requests whenever possible.

Please, do:

Send data only from the Live game version (Odyssey, Horizons 4.0 and future game updates).
Send events in a batch with a reasonable request rate, for example on session start/end and Docked and/or FSDJump events in the journal. Usually it is not needed to do updates more often than that.
Use caching on your side for a stuff that doesn't need to be constantly updated.
Be sure you are sending the correct and actual data.
Reflect any journals/cAPI changes and improvements in your apps, so you are still sending a correct data after the game updates.

Please, don't:

Do NOT send data from the Legacy game version (Horizons 3.8).
Do NOT spam the server with events sent one by one in individual requests. That's why an event batching is there. Be aware that excessive amount of requests in a short time may lead to the API key invalidation and your app will simply stop to work.
Do NOT send data from the game beta versions (handle it in your applications). But you can use these data on your test accounts, of course.
Do NOT send the same events and things over and over, send just the actual/new events. It also applies for getting data (for example commander details), use some caching on your side.

I reserve a right to disallow access for apps/keys that constantly shows high number of errors (so they are not working as intended), are breaking the rules mentioned above or are misusing the API for things against its spirit and intention or against the fair use (like mass data scraping of commanders information, attempts to "spy" on others, etc.).

Linking back to Inara

If do you want to link back to Inara (and links provided in some API events are not provided, sufficient for your needs or require another call), you can link to Inara by using star system, station or minor faction name.

The link formats are following, don't forget to properly URL encode the search strings:

https://inara.cz/elite/starsystem/?search=STARSYSTEMNAME
https://inara.cz/elite/starsystem/?search=STARSYSTEMADDRESS
https://inara.cz/elite/station/?search=STATIONNAME [STARSYSTEMNAME]
https://inara.cz/elite/station/?search=FLEETCARRIERCALLSIGN
https://inara.cz/elite/minorfaction/?search=MINORFACTIONNAME

There are some link examples:

How it works

Inara API is using JSON for its inputs and outputs with a single endpoint. You will simply POST a data in the predetermined structure to the designated URL and it's done.

Input JSON structure consists from header block with Inara API key identifying the user or application, your app details and events block, where are all the events and their properties/data. There is used an event batching, so you can send multiple events at once for the same user and it is recommended to do so. You will find more detailed description and examples in the API documentation.

Simple steps are following:

Get personal Inara API key from the user (or use your application key for general read-only events)
Create an array you will use for the data
Collect stuff from the journals or anything else and put it to your array
Convert the array to JSON
Send this JSON to https://inara.cz/inapi/v1/ using POST method
Get and process returned output (when needed)
Clear your array and go back to point 3.

Simple code example (PHP)

This is just a code snippet as an example how Inara API can be accessed in PHP using cURL. As mentioned earlier, it is pretty simple - just POST JSON data and... that's it. ;)

...

$apitestdata = array();   // your data should be there
$jsondata = json_encode($apitestdata);
$url = "https://inara.cz/inapi/v1/";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsondata);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);   // process the result as you wish

...