====== Unified Uploader and Data Interchange Format ======

===== Goal =====

Create a unified uploader format for EVE-Central, EVE-Marketdata and EVE Marketeer. This data format can also be used for syndication amongst sites.

Discussions are ongoing on the EVE-O Forums: [[https://forums.eveonline.com/default.aspx?g=posts&find=unread&t=18466]]

===== Implementations =====

See the [[unifieduploader:Implementations|]] for sites and clients which support this format.

===== API Entry Point =====

==== Uploads ====

''[SITEROOT]/api/upload''

Methods: POST, GET (parameter = data), PUT (RESTful)

==== Syndication ====

''[SITEROOT]/api/syndicate''

Methods: POST, GET (parameter = data), PUT (RESTful)


===== Message Formats =====

==== Examples ====

The following examples are shown in an expanded form to make them easier to read the actual data would be a single line and not have all the extra whitespace.

=== Orders ===

Market orders, example:
<code javascript>
{
  "resultType" : "orders",
  "version" : "0.1alpha",
  "uploadKeys" : [
    { "name" : "emk", "key" : "abc" },
    { "name" : "ec" , "key" : "def" }
  ],
  "generator" : { "name" : "Yapeal", "version" : "11.335.1737" },
  "currentTime" : "2011-10-22T15:46:00+00:00",
  "columns" : ["price","volRemaining","range","orderID","volEntered","minVolume","bid","issueDate","duration","stationID","solarSystemID"],
  "rowsets" : [
    {
      "generatedAt" : "2011-10-22T15:43:00+00:00",
      "regionID" : 10000065,
      "typeID" : 11134,
      "rows" : [
        [8999,1,32767,2363806077,1,1,false,"2011-12-03T08:10:59+00:00",90,60008692,30005038],
        [11499.99,10,32767,2363915657,10,1,false,"2011-12-03T10:53:26+00:00",90,60006970,null],
        [11500,48,32767,2363413004,50,1,false,"2011-12-02T22:44:01+00:00",90,60006967,30005039]
      ]
    },
    {
      "generatedAt" : "2011-10-22T15:42:00+00:00",
      "regionID" : null,
      "typeID" : 11135,
      "rows" : [
        [8999,1,32767,2363806077,1,1,false,"2011-12-03T08:10:59+00:00",90,60008692,30005038],
        [11499.99,10,32767,2363915657,10,1,false,"2011-12-03T10:53:26+00:00",90,60006970,null],
        [11500,48,32767,2363413004,50,1,false,"2011-12-02T22:44:01+00:00",90,60006967,30005039]
      ]
    }
  ]
}
</code>

As shown in the purposed version multiple data groups would be allowed for different typeIDs. It would also be possible to have the same typeIDs but different regionIDs or both combined.

=== History ===

History, example:

<code javascript>
{
  "resultType" : "history",
  "version" : "0.1alpha",
  "uploadKeys" : [
    { "name" : "emk", "key" : "abc" },
    { "name" : "ec" , "key" : "def" }
  ],
  "generator" : { "name" : "Yapeal", "version" : "11.335.1737" },
  "currentTime" : "2011-10-22T15:46:00+00:00",
  "columns" : ["date","orders","quantity","low","high","average"],
  "rowsets" : [
    {
      "generatedAt" : "2011-10-22T15:42:00+00:00",
      "regionID" : 10000065,
      "typeID" : 11134,
      "rows" : [
        ["2011-12-03T00:00:00+00:00",40,40,1999,499999.99,35223.50],
        ["2011-12-02T00:00:00+00:00",83,252,9999,11550,11550]
      ]
    }
  ]
}
</code>

==== Field Explanations ====

^ Field       ^ JSON Type ^ Description ^
| resultType  | string    | The type of upload. Valid values are "orders" and "history" |
| version     | string    | A Major.Minor number with optional addition "alpha", "beta", etc signifying the data format version. Once format is fixed this will start with "1.0" and only change if format is updated |
| uploadKeys  | array     | An array of objects containing per //endpoint// upload keys |
| generator   | object    | An object with a "name" and "version" pairs to identify the JSON message generator |
| currentTime | string    | The current data/time in ISO 8601 format (example 2011-10-22T15:46:00+00:00) when the JSON message was created. It may also be changed by any //forwarders// as well when the message is re-sent |
| columns     | array     | An array of column names for the data rows. See rows format descriptions below for expected column names |
| rowsets     | array     | An array of data objects as specified in [[#Rowsets]] |

=== UploadKeys ===

^ Name ^ JSON Type ^ Description ^
| name | string    | The name (initials) of the //endpoint// the "key" is for |
| key  | string    | The "key" used by //endpoint// to ID the 'source' the data is from. This can be a simple ID number, or some kind of message digest. See the [[#Key Types]] section for more in depth information |

=== Generator ===

^ Name    ^ JSON Type ^ Description ^
| name    | string    | The name of the //generator// (Application, Library, etc) used to generate (create) the JSON message |
| version | string    | An undefined version string used in identify the version of the JSON message //generator// |

=== Rowsets ===

^ Name        ^ JSON Type      ^ Description ^ 
| generatedAt | string         | The data/time in ISO 8601 format (example 2011-10-22T15:46:00+00:00) when the rowset was created. This allows tracking the 'freshness' of the contained data which is important since data from multiple sources can be generated and received at different times |
| regionID    | null OR number | Id of the region. Can be null if client lacks data |
| typeID      | number         | The typeID of the upload, for history and orders |
| rows        | array          | Contains the actual data rows. See [[#Order Rows]] and [[#History Rows]] descriptions below |

== Order Rows ==

^ Name          ^ JSON Type      ^ Description ^ 
| price         | number         | The price of the order |
| volRemaining  | number         | Remaining volume in order |
| range         | number         | The range the order extends |
| orderID       | number         | The ID of the order |
| volEntered    | number         | The starting volume of the order |
| minVolume     | number         | The minimum volume that can be ordered |
| bid           | true OR false  | Whether the order is a bid (possible: true, false) |
| issueDate     | string         | The date/time the order was issued in ISO 8601 format (example 2011-12-03T10:53:26+00:00) |
| duration      | number         | The amount of days the order will be active |
| stationID     | number         | The station where the order was placed |
| solarSystemID | null OR number | The solar system where the order was placed. Data can be null if client lacks information for result rows |

The order of the 'columns' values determines the order that the 'rows' values should be in. The above order is preferred but should not be assumed by any software decoding the rows instead they must assure they map them in the order given by 'columns'.

== History Rows ==

^ Name     ^ JSON Type ^ Description ^ 
| date     | string    | The date/time the history was issued in ISO 8601 format (example 2011-12-03T00:00:00+00:00) |
| orders   | number    | The number of orders |
| low      | number    | The lowest price of the orders |
| high     | number    | The highest price of the orders |
| average  | number    | The average price of the orders |
| quantity | number    | The quantity of items in the orders |

The order of the 'columns' values determines the order that the 'rows' values should be in. The above order is preferred but should not be assumed by any software decoding the rows instead they must assure they map them in the order given by 'columns'.

=== Comparisons ===
API MarketOrder API columns and Eve cache export columns for comparison:

orderID,charID,stationID,volEntered,volRemaining,minVolume,orderState,typeID,range,accountKey,duration,escrow,price,bid,issued
price,volRemaining,typeID,range,orderID,volEntered,minVolume,bid,issueDate,duration,stationID,regionID,solarSystemID,jumps


=== Key Types ===

How each //endpoint// (application, web site , whatever) uses its "key" is up to them. Any of the other parts of the JSON message maybe used in making the "key" with the restrictions that "uploadKeys" and "currentTime" can not be included. //Forwarders// should not modify anything outside of "uploadKeys" and "currentTime" in the message. If they do they should remove any array elements for //endpoints// in "uploadKeys" where they don't understand how the "key" is formed to prevent a possibly bad message from being past to that //endpoint// which can cause unnecessary extra work for them. All //endpoints// should publish information about any parts of the message that are used in creating their "key" so anyone developing a //forwarder// can know what things to watch out for. It is recommended they also document the formula or process used to form their "key" so it can be implemented by others. In the case of //endpoints// that use any kind of two part public-private encryption digest (think PGP) on the JSON message they should make sure the public part is easily accessible.