Dark Planet Development Platform

EVE Market Data API

API Overview

• Market Orders: These are orders for EVE types placed by characters or corporations. In financial speak, these are limit orders and are either a buy or a sell. Orders can be obtained from the EVE servers (for characters and corporations), from the in-game client, and from various third party sources.
• Historic Market Activity: These are historic price records for EVE types. These are typically daily averages including volume information. Historic prices can be obtained from the in-game client (thought not easily) and third party sources.

Most of the market data fields are provided by the various sources from which market data is obtainable. The source field is provided to make it easier to handle data which may be missing some fields. For example, if some source doesn't or can't provide volEntered, then you can use the source field to identify such data and change your code to handle the missing field properly.

For database storage, the tuple (orderID, typeID, stationID, source) should be used as the key. Technically, order IDs can wrap but this seems unlikley given that they are now 64-bit values.

Historic market activity is represented by instances of IExternalHistoricTradeRecord. The fields of the historic trade interface were designed after the historic dumps recently provided by CCP. The provided fields are a superset of the historic price information available in the EVE client. These fields are:

As with market data, the source field is provided to make it easier to handle heterogenous data sets. For database storage, the tuple (typeID, regionID, date, source) should be used as the key.

Inserting Market Data

    IEveMarketData  marketData = ...get marketdata reference...;
    IEvePersistenceFactory persistFactory = ...get persist reference...;
    
    try {

      marketData.begin();
      IExternalMarketOrderRecord newRecord = persistFactory.getNewExternalMarketOrderRecord(orderID, typeID, stationID, source);
      ...populate other fields of newRecord...
      marketData.getSession().merge(newRecord);
      marketData.commit();

    } catch (HibernateException e) {
      marketData.rollback();
    }

This works for either market orders or historic trade records. The market data API provides a convenience method for each record type to make this slightly easier:

    IEveMarketData  marketData = ...get marketdata reference...;
    IEvePersistenceFactory persistFactory = ...get persist reference...;
    
    try {

      IExternalMarketOrderRecord newRecord = persistFactory.getNewExternalMarketOrderRecord(orderID, typeID, stationID, source);
      ...populate other fields of newRecord...
      marketData.storeEntry(newRecord);

    } catch (HibernateException e) {
      // Commit failed, but storeEntry already rolled back so no need to do that here.
    }

For common tasks, like bulk loading exported market data, the market data API provides the loadExportedClientMarketData method. This method reads market data from an InputStream and will load any data which matches the format of market data exports in the EVE client. As a result, you can use this method to load data from other sources as long as you format it like the EVE client exports. The two other arguments are the sample time and source of the data. Here's an example:

    IEveMarketData  marketData = ...get marketdata reference...;
    
    try {

      // Refer to a file I just exported from the EVE client
      FileInpuStream exportedData = new FileInputStream("Metropolis-Tritanium-2011.06.12 121623.txt");

      // Compute sample time based on the timestamp in the name of the file
      SimpleDateFormat dateParser = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
      dateParser.setTimeZone(TimeZone.getTimeZone("GMT"));
      long sampleTime = dateParser.parse("2011-06-12 12:16:23").getTime();

      // Now load the data.  I use "EveExport" to indicate client exported data.
      marketData.loadExportedClientMarketData(exportedData, sampleTime, "EveExport");

    } catch (IOException e) {
      // The reference implementation batches record loading so even if an exception
      // is thrown SOME records may have been successfully loaded.
    }    

Retrieving Market Data

    IEveMarketData  marketData = ...get marketdata reference...;
    
    try {

      // Assemble a fancy query
      int typeid = ...the type we care about...
      long noLaterThan = ...lower bound on sample time so we get fresh data...
      long asOf = ...lowest timestamp after which order was submitted...
      long[] regions = ...array of regions we care about...

      List results;

      // This query selects all the orders for a particular type in a particular set of
      // regions such that the order has not expired and was entered into the db no
      // later than a particular time (i.e. "asOf").  Note that due to type conversion,
      // the query below may not work for some combinations of OS and SQL.  See the
      // reference implementation for a case where this breaks.
      String fancyQuery = "from org.dps.core.persist.IExternalMarketOrderRecord where " +
        "typeID = :typeid and " +
        "issued <= :asof and " +
        "issued + (duration * 86400000) >= :asof" + 
        "sampleTime >= :nolater and" +
        "regionID in " + Arrays.toString(regions).replace('[', '(').replace(']', ')');

      marketData.begin();

      Query select = marketData.getSession().createQuery(fancyQuery);
      select.setInteger("typeid", typeID);
      select.setLong("asof", asOf);
      select.setLong("nolater", noLaterThan);

      // Java will warn about the lack of cast here, a nit with Hibernate but you can ignore
      results = select.list();
      marketdata.commit();

      ...do something interesting with the data...

    } catch (HibernateException e) {
      marketData.rollback();
    }

Since market order selection is a frequent activity, you can use the convenience method getBBO. This method is a bit complicated, here are what the arguments mean:

The result of this method is the best bid/offer or BBO. The BBO is a pair of market orders representing the buy with the highest offer price, and the sell with the lowest ask price. Depending on your query criteria the BBO may have one or more of the following properties:

• two-sided, having both a bid and offer;
• one-sided, having either a bid or an offer;
• no-sided, having no bid or offer;
• crossed, in which the bid price is higher than the offer price.

At time of writing, there are no convenience methods for accessing historic trade data. You'll need to use the Hibernat-facing methods as demonstrated above.