Mining Ledgers in ESI
This blog post is part of a series of blogs examining best practices for ESI development. Each blog will be published on the 8th of each month during the journey towards XML API and CREST’s termination date. The legacy APIs will be terminated on May 8th, 2018, or earlier if metrics signal a trivial level of usage.
Moon mining is coming to EVE Online on October 24th in the Lifeblood expansion and, for the first time ever, new ESI endpoints will accompany this new feature's release! The new endpoints will be onlined a few hours after downtime on October 24th for Tranquility. We have already released revamped moon mining onto our test server, Singularity, along with the mining ledger ESI endpoints so that you can begin making software for this feature now.
There are three new endpoints to accompany mining ledgers. Let's look a bit closer at each endpoint and how to use them.
Personal Mining Ledgers
There is one endpoint in ESI connected to personal mining ledgers:
GET /v1/characters/{character_id}/mining/
Cache time: 600 seconds (10 minutes)
Required scope: esi-industry.read_character_mining.v1
Pagination: 1000 results per page, returns X-pages HTTP header
With the addition of revamped moon mining in EVE, every mineral you mine will now be recorded into mining ledgers. This endpoint allows you to look at your character's personal mining ledger history for the past 90 days.
Example
First get an access token with the esi-industry.read_character_mining.v1 scope. Make sure to use the SSO base URL https://sisilogin.testeveonline.com if you're doing this against Singularity.
Then, make the following call and replace {character_id} with your character ID and {access_token} with the access token you received:
$ curl --header "Accept: application/json" --header "Authorization: Bearer {access_token}" https://esi.tech.ccp.is/v1/characters/{character_id}/mining/?datasource=singularity
Note: the datasource parameter in this example is only needed when getting data from Singularity before the Lifeblood expansion is released.
Here's a look at an example response for this endpoint:
[
{
"date": "2017-09-21",
"solar_system_id": 30002537,
"type_id": 1227,
"quantity": 5092
},
{
"date": "2017-09-22",
"solar_system_id": 30002537,
"type_id": 1227,
"quantity": 408
},
{
"date": "2017-09-23",
"solar_system_id": 30002537,
"type_id": 1227,
"quantity": 1872
},
{
"date": "2017-09-24",
"solar_system_id": 30002537,
"type_id": 1227,
"quantity": 432
},
{
"date": "2017-09-21",
"solar_system_id": 30002537,
"type_id": 1228,
"quantity": 1000
},
{
"date": "2017-09-21",
"solar_system_id": 30002538,
"type_id": 1227,
"quantity": 1000
}
]
As you can see, mining ledger quantities are aggregated per unique combination of date, solar_system_id and type_id.
You can get more info on the given solar_system_id by dropping it into the /universe/system/{system_id}/ endpoint. You can also drop the given type_id into the /universe/types/{type_id}/ endpoint to see more details on the mineral that was mined.
Corporation Mining Ledgers
The corporation mining ledger endpoints in ESI exist to allow a corporation to track the mining of asteroids that are being observed by a corporation's Upwell Refineries. They do not give the ability to monitor what each member in a corporation is mining. To better understand this "observer" concept, let's look at how moon mining will work on a corporation level in-game:
- A corporation deploys a Upwell Refinery close to a moon.
- The refinery is then fitted with a special moon drilling service module (only one refinery per moon can be fit with a moon drilling module).
- The moon drilling module blasts a chunk of the moon away from its surface and drags it towards the structure. This process takes between one and several weeks.
- Once the chunk of the moon is close enough to the refinery it will be blasted into a small asteroid field which can then be mined.
- The refinery itself will observe who mines this asteroid field and update its mining ledger.
If you would like a deeper understanding of Upwell Refineries you can read this blog.
ESI exposes two endpoints that are connected to corporation mining ledgers:
GET /corporation/{corporation_id}/mining/observers/
Cache time: 3600 seconds (1 hour)
Required scope: esi-industry.read_corporation_mining.v1
Required role: Accountant
Pagination: 1000 results per page, returns X-pages HTTP header
This endpoint exists to list all of your corporation's structures capable of observing moon mining and keeping ledgers. In this case, the list of observers will be a list of Upwell Refineries that a corporation owns which have mining events. Refineries with no mining events will not be shown on this list.
Example
First get an access token with the esi-industry.read_corporation_mining.v1 scope. Make sure to use the SSO base URL https://sisilogin.testeveonline.com if you're doing this against Singularity.
Then, make the following call and replace {corporation_id} with your corporation ID and {access_token} with the access token you received:
$ curl --header "Accept: application/json" --header "Authorization: Bearer {access_token}" https://esi.tech.ccp.is/v1/corporation/{corporation_id}/mining/observers/?datasource=singularity
Note: the datasource parameter in this example is only needed when getting data from Singularity before the Lifeblood expansion is released.
Here's a look at the response for the in-game CCP Corporation on Singularity:
[
{
"last_updated": "2017-09-21",
"observer_id": 1025242944478,
"observer_type": "structure"
},
{
"last_updated": "2017-10-03",
"observer_id": 1025246025947,
"observer_type": "structure"
},
{
"last_updated": "2017-09-28",
"observer_id": 1025246389128,
"observer_type": "structure"
},
{
"last_updated": "2017-09-30",
"observer_id": 1025249693147,
"observer_type": "structure"
}
]
Each observer_id is the ID for a Upwell Refinery that has logged mining events. The CCP corporation owns more than four Upwell Refineries on Singularity, but these do not show up because they have not been participating in any mining activity. You will use the observer_id in the endpoint described below. To get more info on the given structure behind the observer_id you can drop it into the /universe/structures/{structure_id}/ endpoint.
GET /corporation/{corporation_id}/mining/observers/{observer_id}/
Cache time: 3600 seconds (1 hour)
Required scope: esi-industry.read_corporation_mining.v1
Required role: Accountant
Pagination: 1000 results per page, returns X-pages HTTP header
Given an observer_id from the above endpoint, this will list all mining events recorded in the mining ledger for the given observer. Using this, you can tell who mined which type of mineral and which corporation that character belonged to at the time of mining. This endpoint is purposely cached for an hour so that you cannot get real-time updates on whether someone is ninja mining your corporation's minerals. You'll have to police that in-game!
Example
First get an access token with the esi-industry.read_corporation_mining.v1 scope. Make sure to use the SSO base URL https://sisilogin.testeveonline.com if you're doing this against Singularity.
Then, make the following call and replace {corporation_id} with your corporation ID, {observer_id} with an ID of an Upwell Refinery and {access_token} with the access token you received:
$ curl --header "Accept: application/json" --header "Authorization: Bearer {access_token}" https://esi.tech.ccp.is/v1/corporation/{corporation_id}/mining/observers/{observer_id}/?datasource=singularity
Note: the datasource parameter in this example is only needed when getting data from Singularity before the Lifeblood expansion is released.
Here's a look at the response for an Upwell Refinery that the in-game CCP Corporation has on Singularity:
[
{
"last_updated": "2017-09-21",
"character_id": 645704275,
"recorded_corporation_id": 109299958,
"type_id": 45491,
"quantity": 5130
},
{
"last_updated": "2017-09-21",
"character_id": 95633128,
"recorded_corporation_id": 98407839,
"type_id": 45491,
"quantity": 11832
},
{
"last_updated": "2017-09-21",
"character_id": 95633128,
"recorded_corporation_id": 98407839,
"type_id": 45492,
"quantity": 11832
},
{
"last_updated": "2017-09-21",
"character_id": 95633128,
"recorded_corporation_id": 98407839,
"type_id": 1231,
"quantity": 3926
}
]
As we can see, each entry in the mining ledger has a character_id of the character that did the mining, a recorded_corporation_id showing which corporation that character was part of when they did the mining, a type_id for the mineral type that was mined and quantity to show how much of that mineral was mined. This endpoint shows mining events going back 30 days.
You can drop the character_id into the /characters/{character_id}/ endpoint for more details about a given character ID. recorded_corporation_id can be dropped into the /corporations/{corporation_id}/ endpoint and type_id can be dropped into the /universe/types/{type_id}/ endpoint.
What happens when an Upwell Refinery changes ownership?
If corporation A sells its Upwell Refinery to corporation B then corporation A will still see this structure listed in the response from the /corporation/{corporation_id}/mining/observers/ endpoint. However, if corporation A looks up mining events for the sold structure they will only see events that happened in the past 30 days while it was under corporation A's ownership. Any mining events that happen after the transition to corporation B will only be viewable by corporation B.
Conclusion
Team Tech Co. is excited to release new endpoints along with a new feature and we hope this overview can give you a deeper understanding of how to use these three mining ledger endpoints. We look forward to seeing what you will do! As always, you can discuss these endpoints in the tweetfleet slack (use this link to join) in the #esi channel.
o7
-- Team Tech Co.
Recommended CCP Developer Blogs
Nice and ESI (Easy) Task.async_stream -- A blog about concurrently fetching all of EVE's solar systems via ESI using Elixir by CCP AquarHEAD.
Appendix
The following paths have been added or updated in ESI since the previous blog:
- GET /latest/corporations/{corporation_id}/wallets/{division}/transactions/ (v1)
- GET /latest/corporations/{corporation_id}/assets/ (v1)
- GET /latest/corporations/{corporation_id}/blueprints/ (v1)
- GET /latest/corporations/{corporation_id}/titles/ (v1)
- GET /latest/characters/{character_id}/assets/ (v1, spec breaking) -- Migrated to a pagination style
- GET /latest/characters/{character_id}/calendar/{event_id}/attendees/ (v1)
- GET /latest/characters/{character_id}/wallet/journal/ (v2)
- GET /latest/characters/{character_id}/blueprints/ (v2)
- GET /latest/universe/types/{type_id}/ (v3)
- POST /latest/characters/{character_id}/assets/names/ (v1)
- POST /latest/characters/{character_id}/assets/locations/ (v1)
Get a sneak peek at what's coming to ESI by watching our deployment timeline