Dark Planet Development Platform

EVE Server Data API

The EVE Server Data API provides methods for accessing the CCP API server at https://api.eveonline.com. This server accepts requests for character, corporation and reference data, and returns the results in XML format. The DPS server API provides programmatic access to the server and parses the results into Java objects. Certain CCP server calls require credentials in the form of "customizable API keys" which you can create for characters or corporations on the EVE support page. The EVE server API methods happen to be grouped according to which methods require credentials. Therefore, credentials are only required when API handles are created, and are cached for future use.

API Overview

The main gateway interface for server data is org.dps.core.server.IEveServerRequest. This interface provides methods for obtaining the six handles needed for complete server access:

Return value	Method	Function
`IAccountAPIRequest`	getAccountAPIService(`int` keyID, `String` vCode)	Handle for requesting account information.
`ICharacterAPIRequest`	getCharacterAPIService(`int` keyID, `String` vCode, `long` characterID)	Handle for requesting character private information.
`ICorporationAPIRequest`	getCorporationAPIService(`int` keyID, `String` vCode, `long` characterID)	Handle for requesting corporation private information.
`IEveAPIRequest`	getEveAPIService()	Handle for requesting EVE reference information.
`IMapAPIRequest`	getMapAPIService()	Handle for requesting EVE map reference information.
`IServerAPIRequest`	getServerAPIService()	Handle for requesting EVE server status information.

Handles which require credentials will require a "key", which is the customizable API key id, and a "vCode", which is the customizable API vCode hash generated when the key is created. Credentials are cached in the handle instance when it is created. So once you have an instance of ICharacterAPIRequest, for example, you can use it as many times as you like without having to re-submit credentials.

All handles extend IResponse, which is used to capture certain details about each call including error information (if you haven't already, read the API introduction for a description of time value representations):

Return value	Method	Function
`long`	getCachedUntil()	The time until which the server will cache the last response. Normally, you shouldn't bother making the same request again until after this time.
`long`	getCurrentTime()	The current EVE server time when the last request was made.
`int`	getErrorCode()	The error code returned as a result of the last request (if that request resulted in an error).
`long`	getErrorRetryAfterDate()	The time after which the last request can be retried (if that request resulted in an error).
`String`	getErrorString()	A description of the error which resulted from the last request (if that request resulted in an error).
`int`	getEveAPIVersion()	The current EVE API version associated with the last request. Currently this is "2" for most requests.
`boolean`	isError()	True if the last request resulted in an error, and false otherwise.

A consequence of this implementation is that handles can't be used to make concurrent requests. If you need to do that, create two (or more) separate handles.

The return value of a handle method is an interface (or collection) which provides access to the results of the call. A typical example is IContact which is returned from ICharacterApiRequest.requestContacts() (as a collection) and has methods:

Return value	Method	Function
`int`	getContactID()	Unique ID of this contact.
`String`	getContactName()	The name of this contact.
`String`	getList()	The contact list which this contact belongs to.
`double`	getStanding()	The standing the character set for this contact.
`boolean`	isInWatchlist()	True if this contact is in this character's watch list, and false otherwise.

If a handle call results in an error, then this will be indicated in one of two ways:

Every handle method throws java.io.IOException. If the call fails outright or fails to obtain a usable return value, then this exception will be thrown.
If a call succeeds but the EVE server returns an error response, then null is returned and the error fields on the handle are set.

When an exception is not thrown, callers should normally call isError on the handle before proceeding.

Retrieving Server Data

EVE server calls are simple to make once you have an instance of IEveServerRequest. Here's an example which obtains the character sheet for a character:

    IEveServerRequest server = ...get server reference...;

    ICharacterAPIRequest charRequestor = server.getCharacterAPIService(keyID, vCode, characterID);

    ICharacterSheet charSheet = charRequestor.requestCharacterSheet();
    if (!charRequestor.isError())
       System.out.println("CharacterSheet: " + charSheet);
    else
       System.out.println("Unable to get CharacterSheet with error: " + charRequestor.getErrorString());

Note that many of the server APIs have cacheing rules to avoid abuse. You can find links to various sources of EVE API documentation in the "resources" section on our main page. Most of these sources have a good description of the cacheing rules.