API

Einführung

Mit Revelations 2 hat CCP die Schnittstelle (API) für Programmierer überarbeitet und ein erweitertes und deutlich sicheres Konzept erstellt. Die API beinhaltet Zugriffsmöglichkeiten auf Daten des Charakters. Der Zugriff wird dabei in zwei Stufen unterteilt.

Limited API Access Key: Dieser Schlüssel ermöglicht es die Skilldaten und aktuellen Trainingsdaten des Charakers abzurufen. Dieser Schlüssel wird als grundsätzlich sicher und zur Verwendung mit Drittprogrammen empfohlen.

Full Access API Key: Dieser Schlüssel erlaubt den vollen Zugang zu den Charakterdaten. Dies beinhaltet Daten zu Markt-, Corporations- und Besitzinformationen. Dieser Schlüssel sollte nicht an Drittprogramme weitergegeben werden.

Der Sinn der API ist es, Zugang zu Charakterdaten zu gewähren ohne den Benutzernamen und das Passwort des Spielers offen zu legen. CCP empfiehlt grundsätzlich Jedem seine Zugangsdaten ausschließlich für sich zu behalten und an Niemanden weiterzugeben.

[Update]

Mit dem Patch Trinity wurde ebenfalls die API ein wenig vergrössert und auf den Versionsstand 2.0 gebracht. Mit dieser Version ist es möglich Killmails, POS-Übersichten und Füllstand, Marktaufträge, Besitztümer, Sprungrouten, Kartenübersicht der Abschüsse, eroberbare Stationsliste, Corporationsbeschreibungen, Fehlerliste und Industrieaufträge abzurufen.

Erstellung eines API-Schlüssels

Um einen API-Schlüssel zu erstellen, muss man auf http://myeve.eve-online.com/api/default.asp gehen und sich einloggen. Anschließend sieht man den aktuellen Limited API Access Key sofort und hat die Möglichkeit zusätzlich den Full Access API Key zu erzeugen.
Sollte man den aktuellen Limited Key ungültig machen wollen, kann man ebenfalls einen neuen erzeugen lassen. Der alte Schlüssel ist dann ungültig und kann nicht mehr verwendet werden.
Der Schlüssel ist nur gültig in Kombination mit der userID. Diese ist ebenfalls auf der oben genannten Seite zu finden.

Die Authentifizierung

Grundsätzlich benötigt man für die Authentifizierung eine userID sowie den API-Schlüssel.
Beispiel:

• userID: 222834
• apiKey: RGdosyTMjlKIeESvEhAIbpfRAQeoTCcQHRDlZNAjRbImKMvxMdPNr8IFtlkdYEeg

Diese Daten werden als POST-Parameter an die gewünschte Seite gesendet, welche daraufhin die Daten zurückgibt. Nebn diesen beiden Informationen benötigen einige Seiten allerdings auch eine CharacterID. Diese ist dann nötig, wenn man Daten zu einem Charakter haben möchte. Da jeder Account bis zu drei Charaktere besitzen kann muss dieser seperat identifiziert werden. Die CharacterID erhält man von /account/Characters.xml.aspx in welcher alle Charaktere des Accounts aufgelistet sind.

Die Informationsseiten

Die API unterteilt sich in mehrere Seiten welche unterschiedliche Informationen bereitstellen. Die Seiten werden im Folgenden aufgelistet und näher erläutert (Sortiert nach Zugang).

Allgemeines

Skill-Tree

Zugang

/eve/SkillTree.xml.aspx

Inhalt

Alle Skills die es in EVE gibt mit Informationen zu ihren Abhängigkeiten und Rängen.

Authentifizierung

keine nötig

Ref-Type Auflösung

Zugang

/eve/RefTypes.xml.aspx

Inhalt

Angaben zu den verschiedenen Typen der Journal-Einträge. Dies ist notwendig für den Gebrauch der Wallet-Informationen des Charakters/der Corp.

Authentifizierung

keine nötig

Kosmos-Übersicht

Zugang

/map/Sovereignty.xml.aspx

Inhalt

Informationen über jedes Sternensystem des Kosmos mit Angaben zur Hoheitsgewalt des Systems.

Authentifizierung

keine nötig

Character

Account-Übersicht

Zugang

/account/Characters.xml.aspx

Inhalt

Übersicht über alle Charaktere des Accounts einschließlich CharacterID.

Authentifizierung

• userID
• apiKey

Charakter-Übersicht

Zugang

/char/CharacterSheet.xml.aspx

Inhalt

Angaben zu Skills und deren Level des spezifischen Charakters.

Authentifizierung

• userID
• apiKey
• CharacterID

Charakter-Portrait

Zugang

http://img.eve.is/serv.asp

Inhalt Das Charackter-Portrait in der gewuenschten Aufloesung. Authentifizierung

• c (characterID)
• s (size die Angabe 64 entspricht einer Aufloesung von 64x64, 128 gleich 128x128 usw.)

Aktuelles Training

Zugang

/char/SkillInTraining.xml.aspx

Inhalt

Angaben zum aktuellen Skilltraining, welches der Charakter absolviert.

Authentifizierung

• userID
• apiKey
• CharacterID

Skillqueue

Zugang

/char/SkillQueue.xml.aspx

Inhalt

Angaben zur aktuellen Skillqueue des Charakters.

Authentifizierung

• userID
• apiKey
• CharacterID

---

Hinweis

Die folgenden Informationen sind nur mit dem Full Access Key zugänglich!

Charakter-Wallet

Zugang

/char/WalletJournal.xml.aspx

Inhalt

Die Übersicht über das Wallet des Charakters mit Ein- und Ausgaben.

Verwendung

Ein Journal enthält bis zu 1000 Einträge. Es ist möglich alle Einträge der letzten Woche (ab dem aktuellen Tag) einzusehen. Ist das Journal mit 1000 Einträgen für die Woche nicht ausreichend, kann man Schrittweise zurückgehen indem man erneut das Journal abfragt mit der letzten erhaltenen RefID (verwenden als beforeRefID). Um alle Einträge zu erhalten sollte man eine Schleife durchführen die die Daten solange abfragt, bis die Anzahl der zurückgegebenen Einträge weniger als 1000 beträgt.

Authentifizierung

• userID
• apiKey
• CharacterID
• accountKey (immer 1000)
• beforeRefID (0 bei Start, sonst letzte erhaltene refID)

Charakter-Transaktionen

Zugang

/char/WalletTransactions.xml.aspx

Inhalt

Die Informationen über Transaktionen des Charakters.

Verwendung

Ein Journal enthält bis zu 1000 Einträge. Es ist möglich alle Einträge der letzten Woche (ab dem aktuellen Tag) einzusehen. Ist das Journal mit 1000 Einträgen für die Woche nicht ausreichend, kann man Schrittweise zurückgehen indem man erneut das Journal abfragt mit der letzten erhaltenen transID (verwenden als beforeTransID). Um alle Einträge zu erhalten sollte man eine Schleife durchführen die die Daten solange abfragt, bis die Anzahl der zurückgegebenen Einträge weniger als 1000 beträgt.

Authentifizierung

• userID
• apiKey
• CharacterID
• accountKey (immer 1000)
• beforeTransID (0 bei Start sonst letzte erhaltene transID)

Character-Kontostand

Zugang

/char/AccountBalance.xml.aspx

Inhalt

Angaben zum Kontostand des Characters.

Authentifizierung

• userID
• apiKey
• CharacterID

Corporation

Corporation-Kontostände

Zugang

/corp/AccountBalance.xml.aspx

Inhalt

Angaben zu den Kontoständen der Corporation.

Verwendung

Es werden alle sieben Kontoabteilungen ausgegeben, beginnend mit dem accountKey 1000 und bis 1006. Diese Informationen sind nur fuer Piloten mit dem CEO-Status der Corp moeglich.

Authentifizierung

• userID
• apiKey
• CharacterID

Corporation-Besitz

Zugang

/corp/AssetList.xml.aspx

Inhalt

Auflistung des Besitzes der Corporation.

Verwendung

Es werden alle Besitztümer der Corp mit Angabe zum Status und Ort ausgegeben.

Authentifizierung

• userID
• apiKey
• CharacterID

Corp-Wallet

Zugang

/corp/WalletJournal.xml.aspx

Inhalt

Die Übersicht über das Wallet der Corporation des Characters mit Ein- und Ausgaben.

Verwendung

Ein Journal enthält bis zu 1000 Einträge. Es ist möglich alle Einträge der letzten Woche (ab dem aktuellen Tag) einzusehen. Ist das Journal mit 1000 Einträgen für die Woche nicht ausreichend, kann man Schrittweise zurückgehen indem man erneut das Journal abfragt mit der letzten erhaltenen RefID (verwenden als beforeRefID). Um alle Einträge zu erhalten sollte man eine Schleife durchführen die die Daten solange abfragt, bis die Anzahl der zurückgegebenen Einträge weniger als 1000 beträgt.

Authentifizierung

• userID
• apiKey
• CharacterID
• accountKey (1000 - 1006, entsprechen den 7 Corp-Wallets)
• beforeRefID (0 bei Start, sonst letzte erhaltene refID)

Corporation-Transaktionen

Zugang

/corp/WalletTransactions.xml.aspx

Inhalt

Die Informationen über Transaktionen der Corp.

Verwendung

Ein Journal enthält bis zu 1000 Einträge. Es ist möglich alle Einträge der letzten Woche (ab dem aktuellen Tag) einzusehen. Ist das Journal mit 1000 Einträgen für die Woche nicht ausreichend, kann man Schrittweise zurückgehen indem man erneut das Journal abfragt mit der letzten erhaltenen transID (verwenden als beforeTransID). Um alle Einträge zu erhalten sollte man eine Schleife durchführen die die Daten solange abfragt, bis die Anzahl der zurückgegebenen Einträge weniger als 1000 beträgt. Achtung! Diese Informationen sind nur fuer Piloten mit dem CEO-Status der Corp moeglich.

Authentifizierung

• userID
• apiKey
• CharacterID
• accountKey (1000 - 1006, entsprechen den sieben Corp-Wallets)
• beforeTransID (0 bei Start sonst letzte erhaltene transID)

Corporation-Mitgliederübersicht

Zugang

/corp/MemberTracking.xml.aspx

Inhalt

Infos über die Mitglieder der Corporation mit Angaben zu Ort, Login/Logoff, Schiff, Hierarchie usw. Diese Angaben sind nur für Direktoren und CEO der Corp zugänglich!

Authentifizierung

• userID
• apiKey
• CharacterID

Corporation POS-Übersicht

Zugang

/corp/StarbaseList.xml.aspx

Inhalt

Es werden alle POSen der Corporation augeschlüsselt mit Angabe des POS-Typs (typeID identifiziert Art und Rasse der POS). Für nähere Informationen über den POS-Treibstoff muss die itemID der POS genutzt werden in Verbindung mit der Detailabfrage. Diese Informationen sind nur fuer Piloten mit dem Status CEO der Corporation zugänglich.

Authentifizierung

• userID
• apiKey
• CharacterID

Corporation POS-Details

Zugang

/corp/StarbaseDetail.xml.aspx

Inhalt

Es werden Informationen über die aktuell vorhandenen Treibstoffgüter in der POS zurückgegeben. Zur Identifizierung der Güter dient die typeID.

Diese Informationen sind nur fuer Piloten mit dem Status CEO der Corporation zugänglich.

Authentifizierung

• userID
• apiKey
• CharacterID
• itemID (Die itemID der jeweiligen POS, welche aus der POS-Liste zu entnehmen ist)

Abfragen von API-Daten

Da es viele Scriptsprachen und Programmiersprachen gibt und diese die Moeglichkeit bieten die API-Informationen anzufordern sollen im folgenden verschiedene Beispiele aufgelistet werden, wie dies durchgefuehrt werden kann:

Java

Zu ersteinmal ein Beispielcode zur Abfrage von Daten einer API-Seite.

 import java.net.*;
 ...
 try
 {
 	URL url = new URL("http://api.eve-online.com/corp/MemberTracking.xml.aspx"); 
 	URLConnection conn = url.openConnection();
 	conn.setDoOutput(true);
 	conn.addRequestProperty("Content-type", "application/x-www-form-urlencoded");
 	OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
 	wr.write(params);
 	wr.flush();
 	wr.close();
 				
 	result = SaveToFile(conn, fileName);
 }
 catch(Exception e)
 {
 	System.out.println(e.toString());
 }

Der Code ist eigentlich fast selbsterklaerend doch einige kleinere Stellen sind interessant und werden daher kurz erklaert.

 URL url = new URL("http://api.eve-online.com/corp/MemberTracking.xml.aspx");

Hier wird die Seite festgelegt, von wo die Daten hergeholt werden sollen. In diesem Beispiel wurde die Seite Membertracking gewaehlt. Fuer eine variablere Version kann man auch den festen Abschnitt http://api.eve-online.com mit einem variablen Abschnitt verknuepfen (zB. "http://api.eve-online.com"+Site).

 wr.write(params);

Dies ist etwas komplexer. Fuer die Abfrage der Daten werden, wie oben beschrieben, einige zusaetzliche Daten benoetigt. Diese Daten werden als Parameter uebermittelt. In diesem Beispiel wurde eine Variable namens param vorher gefuellt mit entsprechenden Werten. Die Parameter werden als URLCode uebermittelt weshalb eine spezielle Formatierung notwendig ist. Die Erstellung des Wertes soll hier anhand der User-ID gezeigt werden:

 params += URLEncoder.encode("userid", "UTF-8") + "=" + URLEncoder.encode(String.valueOf(123456789),"UTF-8");

Die einzelnen Parameter muessen immer mit dem Parameterbezeichner sowie der Zuweisung des jeweiligen Wertes eingebunden werden. Die verschiedenen Parameter werden durch das Ampersand-Zeichen verknüpft:

 params += "&";

Am Ende enthält die Connection-Variable die empfangenen Daten. In diesem Beispiel werden die Daten mittels einer eigenen Funktion in eine Datei gespeichert:

 result = SaveToFile(conn, fileName);

Innerhalb der Funktion werden die Daten dann Zeilenweise ausgelesen und einen Buffer abgelgt bevor die Daten anschliessend in der Datei abgespeichert werden:

 BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream()));
 String line;
 StringBuffer buf = new StringBuffer();
 String br = "\n\r";
 
 while ((line = rd.readLine()) != null)
 {
 	buf.append(line);
 	buf.append(br);
 }
 ...Buffer in Datei schreiben...

Dies sollten die grundlegendsten Zuege zum Abfragen der API-Daten mittels Java erklaeren. Zur weiteren Verarbeitung koennt/solltet ihr XML-Parser verwenden wie zB. SAX oder XDOM, je nachdem, wie ihr die Daten verarbeiten wollt.

HTML

Um die Daten direkt abzufragen ist es einzig noetig die entsprechende Seite aufzurufen mit uebergabe der notwendigen Werte. Hierbei wird die allgemein gebraeuchliche 'get'-Methode verwendet.
Beispiel:
Abruf der Charakterliste

 http://api.eveonline.com/account/Characters.xml.aspx?userid=1234567&apikey=xyzwasd12340987usw

Die einzelnen Werte sind immer nach dem Feldnamen und dem anschliessenden Gleichzeichen zu setzen. Verbunden werden die einzelnen Angaben per Ampersand und die erste Angabe eingeleitet nach der vollstaendigen Adresse mit einem Fragezeichen.
Mit diesem Wissen kann man alle gaengigen Scriptsprachen die mit HTML zusammenarbeiten verwenden (zB. Formulare mit PHP oder Javascript).