Google Sheets add-on for interacting with EVE ESI API.
- Install the add-on HERE.
- Give the script access to what it needs.
- There will now be a GESI option under the
Add-Ons
option in the menu bar. Click it and then clickGESI => Authorize Characters
. - Click the EVE SSO button in the modal. Login => select what character you want to authorize => Authorize.
- Close the modal.
- (Optional) Repeat step 4 to authorize other characters.
- Done.
By default, one does not have access to GESI functions for use in custom functions in the script editor. In order to gain access to these functions for custom logic, add GESI as a library to your script:
- Install the add-on, following the instructions above.
- Within the script editor, click
Resources => Lbraries...
- At the bottom paste
MKpdmT9YX4m_dA5qB8ReTppeSVVadBdJf
into theAdd a library
box and clickAdd
. - Select the latest version from the dropdown, and click
Save
.
In order to use this, functions must be prepended with GESI
, which maps to the Identifier
field in the Libraries modal. For example, GESI.universe_types();
NOTE: Libraries do not update on their own. When a new version of GESI is released, you will have to manually update the version
dropdown in the Libraries modal.
GESI will automatically update when a new version is released. To see what changed visit the forum thread or the Github Releases page.
NOTE: Changes in the ESI spec, such as adding/removing columns, name changes etc. may break your sheet.
Check out functions.ts. This file lists all the available functions, as well as a description of what they return and the avaliable parameters.
By default GESI uses the version currently on the latest
label. If you wish to use a different version, use the version
parameter. =characters_character_wallet_journal("Blacksmoke16", 1, true, "v5")
. The version can either be a specific version like "v4"
or a label: dev
, legacy
, or latest
.
This happens when GESI
is not authorized to run in the current document. This can be solved by:
- Go to
Add-Ons => Manage add-ons
- Click on
manage
on theGESI
row - Make sure
Use in this document
is checked - Refresh the sheet and should be good
Each authed endpoint that has a name
property that can be used to specify which character's token should be used in that request.
The first character that you auth gets set as your MAIN_CHARACTER
which will be used if you do not provide a value for the name
param for an authed endpoint.
For example =characters_character_assets()
would get the assets for the first character that you authed, i.e. your MAIN_CHARACTER
. =characters_character_assets("My Other Character")
would get assets for My Other Character
.
=getMainCharacter()
will return your currentMAIN_CHARACTER
.=setMainCharacter("Blacksmoke16")
would update yourMAIN_CHARACTER
to beBlacksmoke16
.
In order to improve performance, and reduce the number of requests to ESI (a user can only make 20,000 requests per day between all their sheets), GESI implements caching on the data returned from ESI. The length of time that data will be cached depends on the function and when the data is expected to refresh on ESI's side.
Use -1
as the value for the page parameter. This will return all pages, however it'll take longer to return. If you see the error Internal error when executing the custom function
, it means GESI reached the 30 second custom function execution time limit imposed by Google. A solution for this would be to try calling the function again. This will allow GESI to only fetch new data, and used the cached data for everything else.
Type | Sample |
---|---|
boolean | true or false |
number | 12 |
string | "foo" Notice the double quotes |
Array types are denoted with a []
following the data type of the parameter. An example of an array type could be number[]
where a value for that would be A1:A1
where this range is a column of numbers.
As of now if an endpoint returns a property that is an array of objects nested inside the response, I am JSON stringifying it and displaying it in the column. The parseArray
allows you to parse that array of values and output it like an endpoint function does, wherever you want to. You supply it with the name of the function the data is from, the column you are parsing, and the cell with the array data.
An example of this would be parseArray("character_character_skills", "skills", B2)
where B2
is the cell that contains the data.
There is not built-in way to do this currently, however it is possible.
- Open the
Authorize Characters
modal - Right click on the SSO button and click
Copy link address
- Paste this link into notepad or some text editor
- Within the URL there is query param like
&scopes=
, which is set to a list of all ESI scopes separated by+
signs - Remove all the scopes that you do not want, or add ones that are not added by default
- Copy the URL and paste it into your browser
- Follow SSO flow as normal
- Characters authed using this modified URL will not be able to use any function that requires a scope that was not requested.
- Repeat for additional characters if desired
A common use case is wanting to get the same data from multiple characters. For example, getting the industry jobs of multiple characters into a nice, easy to manage format. Currently this can be achieved by calling =characters_character_industry_jobs()
once, then leaving some space and adding more for each additional characters with opt_headers disabled. While it is an ok workaround it is not optimal, since there could be empty rows, not easily expandable/editable, etc. A better alternative would be to define a new custom function getJobs(character_names)
that will output the industry jobs of the given characters, in a single function call.
/**
* Returns the combined industry jobs belonging to the given characters
* @param {string[]} character_names Character names to get jobs for.
* @param {boolean} opt_headers Default: True, Boolean if column headings should be listed or not.
* @return Combined industry job.
* @customfunction
*/
function getJobs(character_names, opt_headers) {
var characters = character_names.split(",");
var jobs = GESI.characters_character_industry_jobs(false, characters.shift(), opt_headers);
characters.forEach(function(character) {
jobs = jobs.concat(GESI.characters_character_industry_jobs(false, character.trim(), false));
});
return jobs;
}
Which would for three characters would be used like =getJobs("Blacksmoke16, Character2, Character3")
.
This is of course just an example, but the general idea can be used as a template for other endpoint functions and uses.
In-game: Blacksmoke16
Discord: Blacksmoke16#16
Discord Server: https://discordapp.com/invite/eEAH2et
EVE Online and the EVE logo are the registered trademarks of CCP hf. All rights are reserved worldwide. All other trademarks are the property of their respective owners. EVE Online, the EVE logo, EVE and all associated logos and designs are the intellectual property of CCP hf. All artwork, screenshots, characters, vehicles, storylines, world facts or other recognizable features of the intellectual property relating to these trademarks are likewise the intellectual property of CCP hf. CCP hf. has granted permission to GESI to use EVE Online and all associated logos and designs for promotional and information purposes on its website but does not endorse, and is not in any way affiliated with, the GESI. CCP is in no way responsible for the content on or functioning of this website, nor can it be liable for any damage arising from the use of this website.