Difference between revisions of "EVE Swagger Interface"

From EVE University Wiki
Jump to: navigation, search
(Add example section, add section about rate limits)
 
(18 intermediate revisions by 11 users not shown)
Line 1: Line 1:
−
{{stub}}
+
{{Update|Need more information on the endpoints, and fleshing out some how-to guides}}
−
EVE Swagger Interface (ESI) is an API to get data from the EVE server. It replaces [[CREST]] and the XML API which will shut down on May 8th, 2018.<ref>https://developers.eveonline.com/blog/article/important-information-on-the-future-of-the-eve-api</ref>
+
EVE Swagger Interface (ESI) is an API that can be used by [[Third-party tools|third party applications]] to interact with data from the EVE game servers. It replaces CREST and the XML API which were shut down on May 8th, 2018.<ref>https://developers.eveonline.com/blog/article/important-information-on-the-future-of-the-eve-api</ref> The data returned by ESI is in the JSON format.
  
−
Remember that scamming with API is specifically not allowed<ref name="scamming">[https://developers.eveonline.com/blog/article/reminder-no-scamming Reminder to Developers: No Scamming]</ref>
+
ESI has both public-data and authenticated endpoints, the latter of which require a character to log in via [[EVE SSO]] to their character account to gain access to information specific to their character or, provided they have the appropriate corporate roles, their corporation. As of March 2025 there are 76 public-data and 119 Authenticated endpoints (195 total).
  
−
Several guides on how to use ESI exist:
+
CCP has indicated that their goal is to completely replace the [[Static Data Export]] (SDE) with ESI, but as of September 2023, there are still many missing features. For example, industry recipes still require the [[Static Data Export|SDE]].
−
* [https://forums.eveonline.com/t/3-3-0-gesi-google-sheets-esi-library/13406 GESI - Google Sheets ESI Library]
 
−
* [https://www.fuzzwork.co.uk/2017/03/14/using-esi-google-sheets/ Using ESI with Google Sheets]
 
−
* [https://wiki.zansha.space/index.php/SSO_Authentication_in_Microsoft_Power_Query Guide on how to use ESI with MS Excel]
 
  
−
Further some libraries exist to use ESI with Python. For further information see the "See Also" section.
+
As a reminder to developers, it is expressly forbidden for developers of third party applications to use them for ill intent<ref name="scamming">[https://developers.eveonline.com/blog/article/reminder-no-scamming Reminder to Developers: No Scamming]</ref><ref>https://developers.eveonline.com/resource/license-agreement</ref>
  
−
==Api authorization managment==
+
ESI and SSO are commonly used together, however they do have independent features and uses as well. For this reason, they have been split into their own articles. See [[EVE SSO]] for information regarding the character authentication (and management thereof) aspect.
  
−
You can manage API permissions from you at https://community.eveonline.com/support/third-party-applications/
+
== ESI Endpoints ==
 +
ESI provides 195 endpoints, 76 of which related to public data and need no character or client authentication, and 119 of which are authenticated as they relate to privileged information about specific characters or corporations<ref>https://yurix.ch/blog/esi-endpoint-stats.html</ref>.
  
−
In here you can see all applications that have access to your API. You can see exactly what scopes you have authorized for them. You can also revoke authorizations.
+
The general categories these endpoints fall under are:
 +
{| class="wikitable sortable"
 +
! Category !! Public !! Auth !! Description
 +
|-
 +
| Alliances || 4 || || General information about Alliances and their member corporations
 +
|-
 +
| Assets || || 6 || Inventory details for characters and corporations
 +
|-
 +
| Calendar || || 4 || Read and respond to a character's calendar events
 +
|-
 +
| Character || 4 || 10 || Information relating specifically to a character, where it does not fall under any other category.
 +
|-
 +
| Clones || || 2 || Information on a character's clones and their active implants
 +
|-
 +
| Contacts || || 9 || Read Contacts lists for characters, corporations and alliances, and edit them for characters.
 +
|-
 +
| Contracts || 3 || 6 || List public, character and corporate contracts, bids placed on them, and items contained in them.
 +
|-
 +
| Corporation || 4 || 18 || Information relating specifically to a corporation, where it does not fall under any other category.
 +
|-
 +
| Dogma || 5 || || Information regarding Dogma, EVE's system for attributes on items and entities.
 +
|-
 +
| Faction Warfare || 6 || 2 || Public statistics on faction warfare, systems, leaderboards, and a character's statistics.
 +
|-
 +
| Fittings || || 3 || View, create or delete a character's in-game saved fittings.
 +
|-
 +
| Fleets || || 14 || Provides endpoints for a complete breakdown of a fleet's composition, and allows managing it externally.
 +
|-
 +
| Incursions || 1 || || A list of currently active Incursions and some basic info about them
 +
|-
 +
| Industry || 2 || 6 || System Cost Indices, Industry facilities, and all information about a character's active industry jobs.
 +
|-
 +
| Insurance || 1 || || A list of insurance prices for all classes of ships.
 +
|-
 +
| Killmails || 1 || 2 || Retrieve killmails relating to a character, or all details on a killmail for which you have the appropriate information.
 +
|-
 +
| Location || || 3 || View whether a character is online, what they're flying, and where they are located.
 +
|-
 +
| Loyalty || 1 || 1 || List offers available from a provided NPC Corporation's LP Store, and a character's available LP.
 +
|-
 +
| Mail || || 9 || All actions related to viewing, sending and deleting in-game mail for a character.
 +
|-
 +
| Market || 6 || 5 || Market orders and histories, as well as a character or corporation's specific orders.
 +
|-
 +
| Planetary Industry || 1 || 3 || Details on a character's planetary colonies and their layouts, as well as public information on PI Schematics.
 +
|-
 +
| Routes || 1 || || Use the game's algorithms to calculate a route between two systems
 +
|-
 +
| Search || || 1 || Perform a search on the provided string against the chosen categories. If for a character, will also search private things the character can see.
 +
|-
 +
| Skills || || 3 || Information on a character's attributes, skills and skill training queue.
 +
|-
 +
| Sovereignty || 3 || || Lists of sovereignty campaigns, systems and structures.
 +
|-
 +
| Status || 1 || || Status of the game: Whether it's running, what version, and how many players are logged in.
 +
|-
 +
| Universe || 29 || 1 || Just about all general public, static data in the game.
 +
|-
 +
| User Interface || || 5 || Allows opening certain UI windows for a character if they are logged in to the game.
 +
|-
 +
| Wallet || || 6 || Character and Corporation wallet balances and transactions.
 +
|-
 +
| Wars || 3 || || Details on all wars that have happened in the game, including their killmails.
 +
|}
  
−
==See also==
+
== Examples ==
−
* https://community.eveonline.com/news/dev-blogs/introducing-esi/ Original announcement to introduce ESI.
+
To get a list of all alliances in EVE, the  <code>/v2/alliances</code> endpoint can be used. It lists the alliance ID of all alliances. Since it is a public endpoint, it is even possible to a look at it in the browser, although the data comes is in machine-readable JSON: https://esi.evetech.net/latest/alliances/
−
* http://eveonline-third-party-documentation.readthedocs.io/en/latest/crest/index.html
 
−
* https://esi.tech.ccp.is/latest/  
 
−
* https://github.com/devfleet/awesome-eve#developer-tools-resources-and-apis Some ressources to work with ESI.
 
  
−
==References==
+
Some endpoints also support parameter in the URL. For example the type endpoint <code>/v3/universe/types/{type_id}/</code> returns information about a type ID. The rifter has type ID 587. To look up informations like its description, the <code>{type_id}</code> part in the URL is replaced with the type ID. The full URL would then be https://esi.evetech.net/latest/universe/types/587/
 +
 
 +
If possible, CCP requests that users add a descriptive user agent to any ESI request, including a contact email, so that they can be contacted instead of being banned for e.g. causing too much load on the ESI servers. <ref>https://developers.eveonline.com/docs/services/esi/#user-agent</ref>
 +
 
 +
== Tips & Tricks ==
 +
Most ESI endpoints don't have rate-limits, but are error-limited instead, meaning an ESI application is blocked if it makes too many erroneous requests. However, there are two notable exceptions: The <code>/v2/characters/{character_id}/corporationhistory/<code>  and the <code>/v1/markets/{region_id}/history/<code> endpoints have rate limits of 300 requests per IP per minute.<ref>https://forums.eveonline.com/t/resolved-esi-characters-corporation-history/391132/27</ref><ref>https://www.eveonline.com/news/view/eve-evolved-the-future-of-eves-api</ref> This rate limit is unfortunately not documented in the ESI docs.
 +
 
 +
== Resources For Developers ==
 +
There are a number of resources online for developers looking to begin using ESI, many of which also cover SSO for authenticating endpoints.
 +
 
 +
{| class="wikitable"
 +
|-
 +
| https://developers.eveonline.com/docs/ || Community-maintained documentation for ESI.
 +
|-
 +
| https://esi.evetech.net/ui/ || CCP's front-end User Interface for "playing" with ESI and discovering what the various endpoints can do.
 +
|-
 +
| https://github.com/esi/esi-issues || Official Git Repository for tracking issues and requests for ESI.
 +
|-
 +
| https://github.com/esi/esi-issues/issues/1103 || A specific issue on the above repository, that compares ESI to the information available in SDE.
 +
|-
 +
| https://community.eveonline.com/news/dev-blogs/introducing-esi/ || Original Announcement introducing ESI.
 +
|-
 +
| https://github.com/devfleet/awesome-eve#developer-tools-resources-and-apis || Community-maintained list of resources and tools to work with ESI.
 +
|-
 +
| https://forums.eveonline.com/t/3-3-0-gesi-google-sheets-esi-library/13406 || GESI - A library for working with ESI in Google Sheets
 +
|-
 +
| https://developers.eveonline.com/blog/article/using-esi-with-google-sheets || A slightly outdated CCP Dev blog on working with GESI (see above)
 +
|-
 +
| https://www.fuzzwork.co.uk/2017/03/14/using-esi-google-sheets/ || A different guide on working with GESI (see above)
 +
|-
 +
| https://web.archive.org/web/20190310221844/https://wiki.zansha.space/index.php/SSO_Authentication_in_Microsoft_Power_Query || Information on working with ESI in MS Excel with Power Query (archived webpage)
 +
|}
 +
 
 +
== Patch History ==
 +
{{expansion past|
 +
'''03.02.25''' - [https://developers.eveonline.com/blog/deprecation-and-impending-removal-of-esi-opportunities-and-esi-bookmarks Developer Blog Post]
 +
* The bookmark endpoints has been removed after being disabled for more than 5 years<ref>https://developers.eveonline.com/blog/article/temporary-blackout-of-esi-bookmarks</ref>.
 +
* The opportunities endpoints have been removed.
 +
}}
 +
 
 +
== References ==
 
<references />
 
<references />
  
−
 
+
[[Category:Applications]]
−
[[Category:API]]
 

Latest revision as of 13:11, 13 March 2025

This page should be updated due to game changes.
Reason: Need more information on the endpoints, and fleshing out some how-to guides

EVE Swagger Interface (ESI) is an API that can be used by third party applications to interact with data from the EVE game servers. It replaces CREST and the XML API which were shut down on May 8th, 2018.[1] The data returned by ESI is in the JSON format.

ESI has both public-data and authenticated endpoints, the latter of which require a character to log in via EVE SSO to their character account to gain access to information specific to their character or, provided they have the appropriate corporate roles, their corporation. As of March 2025 there are 76 public-data and 119 Authenticated endpoints (195 total).

CCP has indicated that their goal is to completely replace the Static Data Export (SDE) with ESI, but as of September 2023, there are still many missing features. For example, industry recipes still require the SDE.

As a reminder to developers, it is expressly forbidden for developers of third party applications to use them for ill intent[2][3]

ESI and SSO are commonly used together, however they do have independent features and uses as well. For this reason, they have been split into their own articles. See EVE SSO for information regarding the character authentication (and management thereof) aspect.

ESI Endpoints

ESI provides 195 endpoints, 76 of which related to public data and need no character or client authentication, and 119 of which are authenticated as they relate to privileged information about specific characters or corporations[4].

The general categories these endpoints fall under are:

Category Public Auth Description
Alliances 4 General information about Alliances and their member corporations
Assets 6 Inventory details for characters and corporations
Calendar 4 Read and respond to a character's calendar events
Character 4 10 Information relating specifically to a character, where it does not fall under any other category.
Clones 2 Information on a character's clones and their active implants
Contacts 9 Read Contacts lists for characters, corporations and alliances, and edit them for characters.
Contracts 3 6 List public, character and corporate contracts, bids placed on them, and items contained in them.
Corporation 4 18 Information relating specifically to a corporation, where it does not fall under any other category.
Dogma 5 Information regarding Dogma, EVE's system for attributes on items and entities.
Faction Warfare 6 2 Public statistics on faction warfare, systems, leaderboards, and a character's statistics.
Fittings 3 View, create or delete a character's in-game saved fittings.
Fleets 14 Provides endpoints for a complete breakdown of a fleet's composition, and allows managing it externally.
Incursions 1 A list of currently active Incursions and some basic info about them
Industry 2 6 System Cost Indices, Industry facilities, and all information about a character's active industry jobs.
Insurance 1 A list of insurance prices for all classes of ships.
Killmails 1 2 Retrieve killmails relating to a character, or all details on a killmail for which you have the appropriate information.
Location 3 View whether a character is online, what they're flying, and where they are located.
Loyalty 1 1 List offers available from a provided NPC Corporation's LP Store, and a character's available LP.
Mail 9 All actions related to viewing, sending and deleting in-game mail for a character.
Market 6 5 Market orders and histories, as well as a character or corporation's specific orders.
Planetary Industry 1 3 Details on a character's planetary colonies and their layouts, as well as public information on PI Schematics.
Routes 1 Use the game's algorithms to calculate a route between two systems
Search 1 Perform a search on the provided string against the chosen categories. If for a character, will also search private things the character can see.
Skills 3 Information on a character's attributes, skills and skill training queue.
Sovereignty 3 Lists of sovereignty campaigns, systems and structures.
Status 1 Status of the game: Whether it's running, what version, and how many players are logged in.
Universe 29 1 Just about all general public, static data in the game.
User Interface 5 Allows opening certain UI windows for a character if they are logged in to the game.
Wallet 6 Character and Corporation wallet balances and transactions.
Wars 3 Details on all wars that have happened in the game, including their killmails.

Examples

To get a list of all alliances in EVE, the /v2/alliances endpoint can be used. It lists the alliance ID of all alliances. Since it is a public endpoint, it is even possible to a look at it in the browser, although the data comes is in machine-readable JSON: https://esi.evetech.net/latest/alliances/

Some endpoints also support parameter in the URL. For example the type endpoint /v3/universe/types/{type_id}/ returns information about a type ID. The rifter has type ID 587. To look up informations like its description, the {type_id} part in the URL is replaced with the type ID. The full URL would then be https://esi.evetech.net/latest/universe/types/587/

If possible, CCP requests that users add a descriptive user agent to any ESI request, including a contact email, so that they can be contacted instead of being banned for e.g. causing too much load on the ESI servers. [5]

Tips & Tricks

Most ESI endpoints don't have rate-limits, but are error-limited instead, meaning an ESI application is blocked if it makes too many erroneous requests. However, there are two notable exceptions: The /v2/characters/{character_id}/corporationhistory/ and the /v1/markets/{region_id}/history/ endpoints have rate limits of 300 requests per IP per minute.[6][7] This rate limit is unfortunately not documented in the ESI docs.

Resources For Developers

There are a number of resources online for developers looking to begin using ESI, many of which also cover SSO for authenticating endpoints.

https://developers.eveonline.com/docs/ Community-maintained documentation for ESI.
https://esi.evetech.net/ui/ CCP's front-end User Interface for "playing" with ESI and discovering what the various endpoints can do.
https://github.com/esi/esi-issues Official Git Repository for tracking issues and requests for ESI.
https://github.com/esi/esi-issues/issues/1103 A specific issue on the above repository, that compares ESI to the information available in SDE.
https://community.eveonline.com/news/dev-blogs/introducing-esi/ Original Announcement introducing ESI.
https://github.com/devfleet/awesome-eve#developer-tools-resources-and-apis Community-maintained list of resources and tools to work with ESI.
https://forums.eveonline.com/t/3-3-0-gesi-google-sheets-esi-library/13406 GESI - A library for working with ESI in Google Sheets
https://developers.eveonline.com/blog/article/using-esi-with-google-sheets A slightly outdated CCP Dev blog on working with GESI (see above)
https://www.fuzzwork.co.uk/2017/03/14/using-esi-google-sheets/ A different guide on working with GESI (see above)
https://web.archive.org/web/20190310221844/https://wiki.zansha.space/index.php/SSO_Authentication_in_Microsoft_Power_Query Information on working with ESI in MS Excel with Power Query (archived webpage)

Patch History

References

  1. ^ https://developers.eveonline.com/blog/article/important-information-on-the-future-of-the-eve-api
  2. ^ Reminder to Developers: No Scamming
  3. ^ https://developers.eveonline.com/resource/license-agreement
  4. ^ https://yurix.ch/blog/esi-endpoint-stats.html
  5. ^ https://developers.eveonline.com/docs/services/esi/#user-agent
  6. ^ https://forums.eveonline.com/t/resolved-esi-characters-corporation-history/391132/27
  7. ^ https://www.eveonline.com/news/view/eve-evolved-the-future-of-eves-api
  8. ^ https://developers.eveonline.com/blog/article/temporary-blackout-of-esi-bookmarks
Retrieved from "https://wiki.eveuniversity.org/index.php?title=EVE_Swagger_Interface&oldid=221914"