API Journal v1

Last Revision: 9 lis 2018, 14:17:32

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.

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.

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

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
  • Check for Planetary Settlement Latitude/Longitude.
BuyAmmo
  • Remove ammo cost from commander credits.
BuyDrones
  • Remove drone(s) cost from commander credits.
BuyExplorationData
  • Remove exploration data buy price from commander credits.
BuyTradeData
  • Remove trade data buy price from commander credits.
Cargo
  • Set the commander cargo hold.
CargoDepot
  • Update mission cargo progression.
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.
FSSDiscoveryScan
  • Insert body count in current system.
  • Insert non body count in current system.
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.
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.
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.
NpcCrewPaidWage
  • Remove the crew wages from the commander credits.
PVPKill
  • Stored in a temporary table.
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 or if "Delay scanned celestial bodies until docked?" is Off
  • 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.
SellShipOnRebuy
  • Add ship sell price to commander credits.
  • Mark the ship as sold in the commander fleet.
SetUserShipName
  • Update ship name/identification
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.
USSDrop
  • Link USS Drop to current system.
Undocked
  • Remove current ship station.

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",
    "ApproachBody",
    "Bounty",
    "CapShipBond",
    "ChangeCrewRole",
    "ClearSavedGame",
    "CockpitBreached",
    "Commander",
    "Continued",
    "Coriolis",
    "CrewAssign",
    "CrewFire",
    "CrewLaunchFighter",
    "CrewMemberJoins",
    "CrewMemberQuits",
    "CrewMemberRoleChange",
    "DataScanned",
    "DatalinkScan",
    "DatalinkVoucher",
    "DiscoveryScan",
    "DockFighter",
    "DockSRV",
    "DockingCancelled",
    "DockingDenied",
    "DockingGranted",
    "DockingRequested",
    "DockingTimeout",
    "EDDCommodityPrices",
    "EDShipyard",
    "EndCrewSession",
    "EngineerApply",
    "EngineerLegacyConvert",
    "EscapeInterdiction",
    "FactionKillBond",
    "FighterDestroyed",
    "FighterRebuilt",
    "Fileheader",
    "FuelScoop",
    "HeatDamage",
    "HeatWarning",
    "HullDamage",
    "JetConeBoost",
    "JetConeDamage",
    "KickCrewMember",
    "LaunchDrone",
    "LaunchFighter",
    "LaunchSRV",
    "LeaveBody",
    "Liftoff",
    "Market",
    "MassModuleStore",
    "MaterialDiscovered",
    "ModuleArrived",
    "ModuleInfo",
    "ModuleStore",
    "ModuleSwap",
    "Music",
    "NavBeaconScan",
    "NewCommander",
    "NpcCrewRank",
    "Outfitting",
    "Passengers",
    "PowerplayVote",
    "PowerplayVoucher",
    "RebootRepair",
    "ReceiveText",
    "RepairDrone",
    "SRVDestroyed",
    "Scanned",
    "Screenshot",
    "SendText",
    "ShieldState",
    "ShipArrived",
    "ShipTargeted",
    "Shipyard",
    "ShipyardNew",
    "ShutDown",
    "Shutdown",
    "StartJump",
    "Status",
    "StoredModules",
    "SupercruiseEntry",
    "SupercruiseExit",
    "SystemsShutdown",
    "Touchdown",
    "UnderAttack",
    "VehicleSwitch",
    "WingAdd",
    "WingInvite",
    "WingJoin",
    "WingLeave"
]