API Journal V1 / API / EDSM - Elite Dangerous Star Map

API Journal v1

Last Revision: 30.11.2022 10:12:16

The journal API consist only of two endpoints. One to be aware of the discarded events and the other to actually store the events in our database.
The purpose is to have a dynamic API that can accept or deny new events that will come in the future of the game without having the software to write new API calls.

As of UPDATE 14 we will have no choice than removing support for Legacy/Console version of the game. I don't have the meaning/support needed to duplicate the database and maintain it nor I had enough time to prepare for it.

HTTP Request: POST https://www.edsm.net/api-journal-v1

The parameters can be passed as a raw body JSON or like a form/multipart.
Note that GET request will not be followed for security reasons.

Parameter	Default	Description
commanderName*	`NULL`	The name of the commander as registered on EDSM. Your commander name for example is: Guest.
apiKey*	`NULL`	The API Key associate the commander name with his account. API Key can be generated under the settings > My API Key tab. API Key is used to ensure your private informations stays private.
fromSoftware*	`NULL`	Name of the software used to submit the data.
fromSoftwareVersion*	`NULL`	Version of the software used to submit the data.
fromGameVersion*	`NULL`	Version of the game used to submit the data. As of 29/11/2022, Frontier have separated the game into two different instances, so those two fields are now mandatory in order to check from which version the data is coming. ONLY THE LIVE VERSION IS ACCEPTED See: https://github.com/EDCD/EDDN/blob/live/docs/Developers.md#gameversions-and-gamebuild
fromGameBuild*	`NULL`	Version of the build game used to submit the data.
message*	`NULL`	The message line from the journal without any modification. In order to send messages by batch, you can also send a list of message line from the journal. We said without modification, but you may be aware that event passed into the journal does not keep track of every state we need. If you send events by batch, the API will try to figure which state the game is in, if you're tracking the game state from your application, or send events one by one, see the transient state description.

Transient states

Most of the events do not track the state of the game, meaning that if you fed event one by one you cannot know for sure when the event happened.
Transient states are added in order to fill that gap by providing extra informations that can be used for example to know the current system or ship.

Parameter	Default	Description
_systemAddress	`NULL`
_systemName	`NULL`
_systemCoordinates	`NULL`
_marketId	`NULL`
_stationName	`NULL`
_shipId	`NULL`

var updateGameStatus = function(entry){
    if(entry.event == 'LoadGame')
    {
        gameStatus.systemId         = null;
        gameStatus.system           = null;
        gameStatus.coordinates      = null;
        gameStatus.stationId        = null;
        gameStatus.station          = null;
    }

    if(entry.event == 'SetUserShipName')
    {
        gameStatus.ship.id              = entry.ShipID;
    }

    if(entry.event == 'ShipyardBuy')
    {
        gameStatus.ship.id              = null;
    }

    if(entry.event == 'ShipyardSwap')
    {
        gameStatus.ship.id              = entry.ShipID;
    }

    if(entry.event == 'Loadout')
    {
        gameStatus.ship.id              = entry.ShipID;
    }

    if(entry.event == 'Undocked')
    {
        gameStatus.stationId            = null;
        gameStatus.station              = null;
    }

    if(['Location', 'FSDJump', 'Docked'].indexOf(entry.event) !== -1)
    {
        // Docked don't have coordinates, if system changed reset
        if(entry.StarSystem != gameStatus.system)
        {
            gameStatus.coordinates  = null;
        }

        if(entry.StarSystem != 'ProvingGround' && entry.StarSystem != 'CQC')
        {
            if(entry.SystemAddress != undefined)
            {
                gameStatus.systemId = entry.SystemAddress;
            }

            gameStatus.system       = entry.StarSystem;

            if(entry.StarPos != undefined)
            {
                gameStatus.coordinates = entry.StarPos;
            }
        }
        else
        {
            gameStatus.systemId     = null;
            gameStatus.system       = null;
            gameStatus.coordinates  = null;
        }

        if(entry.MarketID != undefined)
        {
            gameStatus.stationId = entry.MarketID;
        }
        if(entry.StationName != undefined)
        {
            gameStatus.station = entry.StationName;
        }
    }

    if(['JoinACrew', 'QuitACrew'].indexOf(entry.event) !== -1)
    {
        if(entry.event == 'JoinACrew' && entry.Captain != gameStatus.cmdr)
        {
            gameStatus.sendEvents = false;
        }
        else
        {
            gameStatus.sendEvents = true;
        }

        gameStatus.systemId         = null;
        gameStatus.system           = null;
        gameStatus.coordinates      = null;
        gameStatus.stationId        = null;
        gameStatus.station          = null;
    }

    entry._systemAddress        = gameStatus.systemId;
    entry._systemName           = gameStatus.system;
    entry._systemCoordinates    = gameStatus.coordinates;
    entry._marketId             = gameStatus.stationId;
    entry._stationName          = gameStatus.station;
    entry._shipId               = gameStatus.ship.id;

    return entry;
};

Error codes

Code	Message
`100`	OK Everything went fine!
`101`	Message already stored The journal message was already processed in our database.
`102`	Message older than the stored one The journal message was already in a newer version in our database.
`103`	Duplicate event request Each event passed to the API is stored in cache for around 300 seconds, preventing multiple software from requesting the same event.
`104`	Crew session Commander is in a crew session without being the captain. As such we do not register any logs.

`201`	Missing commander name Commander name is a required parameter and must be one of the registered user on EDSM.
`202`	Missing API key API Key is a required parameter.
`203`	Commander name/API Key not found The commander name or the API Key provided does not correspond to any user in our database.
`204`	Software/Software version not found In order to be able to blacklist incorrect software, we require both the name and the version of the software used to send the informations.
`205`	Blacklisted software You need to update the used software, or see with the developer of the software about potential issues encountered.
`206`	Cannot decode JSON JSON message could not be decoded
`207`	Game/Build version not found In order to be able to blacklist incorrect game version and different Legacy/Live version of the game, we require both the version and the build of the game used to send the informations.
`208`	Game/Build version too old Legacy versions of the game are NOT supported.

`301`	Message not found The journal message was not provided.
`302`	Cannot decode message JSON The journal message could not de decoded or is not in a valid JSON format.
`303`	Missing timestamp/event from message Missing timestamp/event key from the journal message.
`304`	Discarded event This event is part of the discarded events and will not be processed. See: `GET https://www.edsm.net/api-journal-v1/discard`

`401`	Category unknown
`402`	Item unknown The current alias of the item is not currently in EDSM database. Try again later to update the event if needed.
`451`	System probably non existant The provided system probably don't exists in the game or was moved elsewhere.
`452`	An entry for the same system already exists just before the visited date. To avoid multiple entries for the same systems at a nearly same date, we check the before and the after submission according to the visited date provided. That can happens when other third party tools does not have the exact same server time. AKA: You cannot submit twice the same system in a row (A to A), it must be A to B to A.
`453`	An entry for the same system already exists just after the visited date. See `452`.

`500`	Exception: %% An unexpected exception!
`501`	%% Normally a debug message you should not see ;)

Events

	Event	Description
	`ApproachSettlement`	Update Planetary Settlement Latitude/Longitude.
	`BackPack`	Set the commander backpack.
	`Backpack`	Set the commander backpack.
	`BackpackChange`	Remove/Add the micro resource from the commander backpack.
	`BookTaxi`	Remove book taxi cost from commander credits.
	`BuyAmmo`	Remove ammo cost from commander credits.
	`BuyDrones`	Remove drone(s) cost from commander credits.
	`BuyExplorationData`	Remove exploration data buy price from commander credits.
	`BuyMicroResources`	Add micro resource cost from commander backpack. Remove micro resource cost from commander credits.
	`BuyTradeData`	Remove trade data buy price from commander credits.
	`CancelTaxi`	Refund book taxi cost to commander credits.
	`Cargo`	Set the commander cargo hold.
	`CargoDepot`	Update mission cargo progression.
	`CarrierJump`	Set commander position in flight logs.
	`CodexEntry`	Check for Codex Entry.
	`CollectCargo`	Add the cargo to the commander cargo hold.
	`CommitCrime`	Register commander crime.
	`CommunityGoal`	Insert/Update community goal details. Insert/Update commander status on community goal.
	`CommunityGoalDiscard`	Discard commander from community goal.
	`CommunityGoalJoin`	Join commander to community goal.
	`CommunityGoalReward`	Add community goal reward to commander credits.
	`CrewHire`	Remove the crew hiring cost from the commander credits.
	`Died`	Register commander death.
	`Docked`	Update ship current system/station.
	`EjectCargo`	Remove the cargo from the commander cargo hold.
	`EngineerContribution`	Remove donation from the commander credits. Remove commodities from the commander cargo hold.Remove materials/data from the commander inventory.
	`EngineerCraft`	Update engineer unlock grade. Remove the ingredients from the commander inventory.
	`EngineerProgress`	Update engineer(s) rank Update engineer(s) stage
	`FSDJump`	Set commander position in flight logs. Update ship current system.Remove fuel from ship.
	`FSDTarget`	Update a system ID64 if missing
	`FSSAllBodiesFound`	Insert/Update body count in current system. Lock the final body count
	`FSSDiscoveryScan`	Insert body count in current system. Update if wrong and not locked
	`FetchRemoteModule`	Remove module transfer price from the commander credits.
	`Friends`	Update friends status on EDSM
	`Interdicted`	Link Interdiction to current system.
	`Interdiction`	Link Interdiction to current system.
	`JoinACrew`	Only used to set the crew session state.
	`LoadGame`	Set credits to current value (Reason: Regulation). Update ship fuel level.
	`Loadout`	Update current shipID. Insert ship if not known.Update ship paintjob.Update ship hull value, modules value and rebuy.Store modules.Unlock Technology Broker.
	`Location`	Update ship current system/station. Insert FSDJump in case of mismatched location
	`MarketBuy`	Remove commodity buy price from commander credits. Add commodity to commander cargo hold.
	`MarketSell`	Add commodity sell price to commander credits. Remove commodity from commander cargo hold.
	`MaterialCollected`	Add the material/data to the commander inventory.
	`MaterialDiscarded`	Remove the material/data from the commander inventory.
	`MaterialTrade`	Remove the paid material from the commander inventory. Add the received material to the commander inventory.
	`Materials`	Overwrite the materials to the commander inventory. Overwrite the data to the commander inventory.
	`MiningRefined`	Add the refined mining fragments to the commander cargo hold.
	`MissionAbandoned`	Set mission status to "Abandoned". Remove fine from the commander credits.
	`MissionAccepted`	Insert the new mission.
	`MissionCompleted`	Set mission status to "Completed". Add "Reward" to commander credits.Remove "Donation" from commander credits.Add commodities rewarded to the commander cargo hold.
	`MissionFailed`	Set mission status to "Failed". Remove fine from the commander credits.
	`MissionRedirected`	Redirect mission to new destination.
	`Missions`	Update Missions status. We are still looking of what to do exactly from that event ;)
	`ModuleBuy`	Remove module cost from commander credits. Event is inserted only if cost is superior to 0.Add sell price if old module is sold.Update ship paintjob.
	`ModuleBuyAndStore`	Remove module cost from commander credits. Event is inserted only if cost is superior to 0.Add sell price if old module is sold.
	`ModuleRetrieve`	Remove module retrieve cost from commander credits. Event is inserted only if cost is present and superior to 0.
	`ModuleSell`	Add module sell price to commander credits. Event is inserted only if cost is present and superior to 0.
	`ModuleSellRemote`	Add module sell price to commander credits. Event is inserted only if cost is present and superior to 0.
	`MultiSellExplorationData`	Add exploration data sell price to commander credits.
	`NpcCrewPaidWage`	Remove the crew wages from the commander credits.
	`PayBounties`	Remove bounties from commander credits.
	`PayFines`	Remove fines from commander credits.
	`PayLegacyFines`	Remove legacy fines from commander credits.
	`Powerplay`	Pledge the commander to the Power. Update rank, merits, votes and time pledged.
	`PowerplayCollect`	Add the cargo to the commander cargo hold. Pledge the commander to the Power.
	`PowerplayDefect`	Pledge the commander to the new Power.
	`PowerplayDeliver`	Remove the cargo from the commander cargo hold. Pledge the commander to the Power.
	`PowerplayFastTrack`	Remove the Fast Track cost from the commander credits. Pledge the commander to the Power.
	`PowerplayJoin`	Pledge the commander to the Power.
	`PowerplayLeave`	Unpledge the commander to the Power.
	`PowerplaySalary`	Add the power salary to the commander credits. Pledge the commander to the Power.
	`Progress`	Update the commander ranks progression.
	`Promotion`	Update the commander new promoted rank. Reset the promoted rank progression to 0.
	`QuitACrew`	Only used to set the crew session state.
	`Rank`	Update the commander ranks.
	`RedeemVoucher`	Add voucher redeem amount to commander credits.
	`RefuelAll`	Remove refuel cost. TODO: Refuel ship if newer than the stored value and transient state available.
	`RefuelPartial`	Remove refuel cost. TODO: Refuel ship if newer than the stored value and transient state available.
	`Repair`	Remove repair cost from commander credits.
	`RepairAll`	Remove repair cost from commander credits.
	`Reputation`	Update the commander reputation with superpowers.
	`RestockVehicle`	Remove vehicule price from commander credits.
	`Resurrect`	Remove resurrect cost from commander credits Mark current ship as sold if free rebuy
	`SAAScanComplete`	Insert celestial body in user map. Update celestial body first mapping.
	`Scan`	Insert body if using EDSM importer, if "Delay scanned celestial bodies until docked?" is Off or if scan is older than a month. Insert celestial body in user scan.Update celestial body first discovery.
	`ScientificResearch`	Remove the material/data from the commander inventory.
	`SearchAndRescue`	Add reward to commander credits. Remove item from commander cargo hold.
	`SelfDestruct`	Register commander death.
	`SellDrones`	Add drone(s) sell price to commander credits.
	`SellExplorationData`	Add exploration data sell price to commander credits.
	`SellMicroResources`	Add micro resources sell price to commander credits. Remove micro resources from commander backpack.
	`SellShipOnRebuy`	Add ship sell price to commander credits. Mark the ship as sold in the commander fleet.
	`SetUserShipName`	Update ship name/identification
	`ShipLocker`	Set the ship locker.
	`ShipyardBuy`	Remove ship cost from commander credits. Ship creation is done in the `Loadout` event.Add sell price if old ship is sold.
	`ShipyardSell`	Add ship sell price to commander credits. Mark the ship as sold in the commander fleet.
	`ShipyardSwap`	Update current shipID.
	`ShipyardTransfer`	Remove ship trasnfer cost from commander credits. Update transfered ship parking.
	`StartUp`	Return current system for ED Market Connector.
	`Statistics`	Update the commander statistics.
	`StoredShips`	Update/Insert all commander stored ships
	`Synthesis`	Remove the materials/data from the commander inventory if newer than the last update.
	`TechnologyBroker`	Unlock the items Remove the materials/data/commodities from the commander inventory if newer than the last update.
	`TradeMicroResources`	Remove the micro resource from the commander backpack. Add received micro resource to the commander backpack.
	`USSDrop`	Link USS Drop to current system.
	`Undocked`	Remove current ship station.
	`UseConsumable`	Remove consumable from commander backpack.

HTTP Request: GET https://www.edsm.net/api-journal-v1/discard

The purpose of this endpoint is to give software an insight of which events will be discarded by the API.
This is a fluctuent information that need to be checked ideally on software reboot to be kept up to date with the kind of events we proceed.

For any events in that list, it is not necessary to make a call to EDSM.

Output:

[
    "AfmuRepairs",
    "AppliedToSquadron",
    "ApproachBody",
    "AsteroidCracked",
    "BookDropship",
    "Bounty",
    "CancelDropship",
    "CapShipBond",
    "CargoTransfer",
    "CarrierBankTransfer",
    "CarrierBuy",
    "CarrierCrewServices",
    "CarrierDecommission",
    "CarrierDepositFuel",
    "CarrierDockingPermission",
    "CarrierFinance",
    "CarrierJumpCancelled",
    "CarrierJumpRequest",
    "CarrierModulePack",
    "CarrierNameChange",
    "CarrierStats",
    "CarrierTradeOrder",
    "ChangeCrewRole",
    "ClearSavedGame",
    "CockpitBreached",
    "CollectItems",
    "Commander",
    "Continued",
    "Coriolis",
    "CreateSuitLoadout",
    "CrewAssign",
    "CrewFire",
    "CrewLaunchFighter",
    "CrewMemberJoins",
    "CrewMemberQuits",
    "CrewMemberRoleChange",
    "CrimeVictim",
    "DataScanned",
    "DatalinkScan",
    "DatalinkVoucher",
    "DisbandedSquadron",
    "DiscoveryScan",
    "Disembark",
    "DockFighter",
    "DockSRV",
    "DockingCancelled",
    "DockingDenied",
    "DockingGranted",
    "DockingRequested",
    "DockingTimeout",
    "DropItems",
    "DropshipDeploy",
    "EDDCommodityPrices",
    "EDDItemSet",
    "EDShipyard",
    "Embark",
    "EndCrewSession",
    "EngineerApply",
    "EngineerLegacyConvert",
    "EscapeInterdiction",
    "FSSBodySignals",
    "FSSSignalDiscovered",
    "FactionKillBond",
    "FighterDestroyed",
    "FighterRebuilt",
    "Fileheader",
    "FuelScoop",
    "HeatDamage",
    "HeatWarning",
    "HullDamage",
    "InvitedToSquadron",
    "JetConeBoost",
    "JetConeDamage",
    "JoinedSquadron",
    "KickCrewMember",
    "LaunchDrone",
    "LaunchFighter",
    "LaunchSRV",
    "LeaveBody",
    "LeftSquadron",
    "Liftoff",
    "LoadoutEquipModule",
    "Market",
    "MassModuleStore",
    "MaterialDiscovered",
    "ModuleArrived",
    "ModuleInfo",
    "ModuleStore",
    "ModuleSwap",
    "Music",
    "NavBeaconScan",
    "NavRoute",
    "NavRouteClear",
    "NewCommander",
    "NpcCrewRank",
    "Outfitting",
    "PVPKill",
    "Passengers",
    "PowerplayVote",
    "PowerplayVoucher",
    "ProspectedAsteroid",
    "RebootRepair",
    "ReceiveText",
    "RepairDrone",
    "ReservoirReplenished",
    "SAASignalsFound",
    "SRVDestroyed",
    "ScanBaryCentre",
    "ScanOrganic",
    "Scanned",
    "Screenshot",
    "SendText",
    "SharedBookmarkToSquadron",
    "ShieldState",
    "ShipArrived",
    "ShipTargeted",
    "Shipyard",
    "ShipyardNew",
    "ShutDown",
    "Shutdown",
    "SquadronCreated",
    "SquadronStartup",
    "StartJump",
    "Status",
    "StoredModules",
    "SuitLoadout",
    "SupercruiseEntry",
    "SupercruiseExit",
    "SwitchSuitLoadout",
    "SystemsShutdown",
    "Touchdown",
    "UnderAttack",
    "VehicleSwitch",
    "WingAdd",
    "WingInvite",
    "WingJoin",
    "WingLeave"
]