mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-19 19:25:51 +00:00

Files

mDuo13 15b122c918 [DOC] added Charts API (incomplete draft)

2015-03-04 17:46:25 -08:00

17 KiB

Raw Blame History

Ripple Charts API

The Ripple Charts API, also known as the Data API, provides past and present information about the state of the Ripple Network through a REST-like API, with additional information calculated for analysis purposes. The Ripple Charts API is used as a data source by applications such as Ripple Charts and ripple.com.

Architecture
Setup
API Method Reference

Architecture

The Ripple Charts API is a Node.js application that uses CouchDB and Redis as its datastore. The Charts API continually monitors rippled for new ledgers and imports them.

Components

Ledger Importer

The ledger importer imports ledgers from the Ripple Network into the data store. The process is set up to import continously in real time as ledgers are validated, and also import historical ledgers.

Data Store

The data store uses CouchDB to store ledgers as a JSON document. To retrieve structured data from the ledgers, the Charts API uses "views" that index specific elements from the ledger into a format that can be queried efficiently. For example, one view collects all successful transactions that exercise offers and indexes them according to the currencies, issuers, and date, and returns the amounts and prices of the exercised offers. We can then query this view and group the indexed results by time increments to get an array of offers excercised over time for a given pair of currencies.

API Server

Accessing the historical data is not done by querying the database directly but through a node.js API server. The server takes requests in the form of JSON data, interprets it into one or several couchDB queries, processes the data as necessary and returns the results.

Memory Cache

To reduce the load on CouchDB, the Charts API uses Redis as a caching layer. The cache expects the data stored in CouchDB to be accurate and up to date, so the API automatically disables the cache if the importer is unable to keep up. When the importer catches up, the API restarts the cache again.

Setup

Basic setup of the Ripple Charts API involves the following steps:

Install Node.js
Install CouchDB, or get access to a hosted CouchDB.
Install Redis. (This step is optional, but strong recommended.)
Clone the Ripple Charts repository:
git clone https://github.com/ripple/ripple-data-api.git
Install dependencies using npm:
npm install
Copy the example configuration files to their expected locations:
In the ripple-data-api top folder:
cp db.config.json.example db.config.json
cp deployment.environments.json.example deployment.environments.json
Modify the configuration files, providing the addresses and credentials of your CouchDB and Redis databases.
Push design documents to CouchDB:
grunt updateViews
(This requires write permissions to the CouchDB instance.)

At this point, the Ripple Charts API is installed, but not running, and has no data imported. You can start the API service or start the ledger importer in any order.

Start API Service

The following command starts the API service:

grunt watch

(This requires read permissions to CouchDB. Write permissions are not necessary.)

Start Ledger Importer

The following command starts the ledger importer service:

node db/importer

Alternatively, you can use the experimental websocket-based importer:

node db/import

(Either way, you need write permission to the CouchDB database.)

API Objects

Dates and Times

The Ripple Charts API uses Moment.js to parse strings, and therefore accepts any date-time string that Moment.js recognizes as input.

The Ripple Charts API always outputs dates in UTC, in the following format:

YYYY-MM-DDThh-mm-ss+00:00

For example: 2015-03-01T00:00:00+00:00 (midnight exactly on March 3, 2015 UTC)

Currency Objects

Many methods define a currency as an object with the following fields:

Field	Value	Description
currency	String	Three-letter ISO 4217 Currency Code string, or a 160-bit hex string according to Ripple's internal Currency format.
issuer	String	Account address of the counterparty holding the currency. Usually an issuing gateway in the Ripple network. Omitted for XRP.

Response Formats

Several methods provide a format parameter, which lets you request results in one of three formats:

csv - Comma-separated-values table. Each line represents one result or interval, with its attributes in columns.
json - The request contains some top-level information at the top level, and a results array. Each member of the results array is a JSON object with attributes and values that represent one result or interval.
Two-dimensional array format - If neither csv nor json is specified, the API returns an array of JSON arrays, in a format that resembles CSV. The first member of the top-level array is an array of table headers, and each subsequent member is a nested array representing one result or interval, with its members corresponding to the attribute names in the header row.

API Method Reference

Ripple Labs runs a public instance of the Ripple Charts API with full data, available at:

https://api.ripplecharts.com/api

The API provides the following methods:

Account Offers Exercised - POST /account_offers_exercised
Account Transaction Stats - POST /account_transaction_stats
Account Transactions - POST /account_transactions
Accounts Created - POST /accounts_created
Exchange Rates - POST /exchange_rates
Issuer Capitalization - POST /issuer_capitalization
Ledgers Closed - POST /ledgers_closed
Market Traders - POST /market_traders
Offers - POST /offers
Offers Exercised - POST /offers_exercised
Top Markets - POST /top_markets
Total Network Value - POST /total_network_value
Total Value Sent - POST /total_value_sent
Transaction Stats - POST /transaction_stats
Value Sent - POST /value_sent

offers_exercised

[Source]

Retrieve information about currency-exchange orders being exercised on the network, for a specific pair of currencies and timeframe.

15-minute increments

POST /offers_exercised
{
    "base": {
        "currency": "USD",
        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
    },
    "counter": {
        "currency": "BTC",
        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
    },
    "endTime": "2015-03-01T00:00Z",
    "startTime": "2015-03-01T12:00Z",
    "timeIncrement": "minute",
    "timeMultiple": 15,
    "format": "json"
}

Expanded

POST /offers_exercised
{
    "base": {
        "currency": "USD",
        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
    },
    "counter": {
        "currency": "BTC",
        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
    },
    "endTime": "2015-03-01T00:00Z",
    "startTime": "2015-03-01T23:59Z",
    "reduce": false,
    "limit": 5,
    "offset": 0,
    "format": "json"
}

The request includes the following body parameters:

Field	Value	Description
base	Object (Currency Object)	One of the currencies being exchanged.
counter	Object (Currency Object)	The other of the currencies being exchanged.
startTime	String (Date-Time)	Retrieve information starting at this time.
endTime	String (Date-Time)	Retrieve information ending at this time.
timeIncrement	String	(Optional) Divide results into intervals of the specified length: `year`, `month`, `day`, `hour`, `minute`, or `second`. The value `all` collapses the results into just one interval. Defaults to `all`.
timeMultiple	Number	(Optional) Create larger intervals that are this many times the size of the `timeIncrement` (for example, 15-minute intervals). Defaults to 1.
descending	Boolean	(Optional) If true, return results in descending order. Defaults to false.
reduce	Boolean	(Optional) If `false`, include transactions individually instead of collapsing them into results over time. Defaults to `true`. Ignored if `timeIncrement` is provided.
limit	Number	(Optional) If reduce is `false`, this value defines the maximum number of transactions to return in one response. Use with `offset` to paginate results. Defaults to 500.
offset	Number	(Optional) If reduce is `false`, this value defines a number of transactions to skip before returning results. Use with `limit` to paginate results. Defaults to 0.
format	String	(Optional) The format to return results in. Use `csv` to return results in CSV format or `json` to return results as JSON. If omitted, defaults to a CSV-like JSON array format.

Response Format

An example of a successful response:

15-minute increments

{
    "startTime": "2015-03-01T00:00:00+00:00",
    "endTime": "2015-03-01T12:00:00+00:00",
    "base": {
        "currency": "USD",
        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
    },
    "counter": {
        "currency": "BTC",
        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
    },
    "timeIncrement": "minutes",
    "timeMultiple": 15,
    "results": [
        {
            "startTime": "2015-03-01T00:45:00+00:00",
            "openTime": "2015-03-01T00:52:20+00:00",
            "closeTime": "2015-03-01T00:52:20+00:00",
            "baseVolume": 683.2001467024601,
            "counterVolume": 2.679229505167318,
            "count": 1,
            "open": 0.0039215880120912015,
            "high": 0.0039215880120912015,
            "low": 0.0039215880120912015,
            "close": 0.0039215880120912015,
            "vwap": 0.003921588012091202,
            "partial": false
        },
        {
            "startTime": "2015-03-01T09:45:00+00:00",
            "openTime": "2015-03-01T09:45:30+00:00",
            "closeTime": "2015-03-01T09:48:40+00:00",
            "baseVolume": 6025.771839536825,
            "counterVolume": 23.67880093810258,
            "count": 43,
            "open": "0.00391389432485323",
            "high": 0.003945508916212113,
            "low": "0.003912889366625167",
            "close": 0.003921642784865358,
            "vwap": 0.003929588037625179,
            "partial": false
        },
        {
            "startTime": "2015-03-01T11:45:00+00:00",
            "openTime": "2015-03-01T11:59:40+00:00",
            "closeTime": "2015-03-01T11:59:40+00:00",
            "baseVolume": 30.990503463384982,
            "counterVolume": 0.12348600141122801,
            "count": 1,
            "open": "0.003984640054561433",
            "high": "0.003984640054561433",
            "low": "0.003984640054561433",
            "close": "0.003984640054561433",
            "vwap": 0.003984640054561414,
            "partial": false
        }
    ]
}

Expanded

{
    "startTime": "2015-03-01T00:00:00+00:00",
    "endTime": "2015-03-01T23:59:00+00:00",
    "base": {
        "currency": "USD",
        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
    },
    "counter": {
        "currency": "BTC",
        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
    },
    "timeIncrement": "all",
    "results": [
        {
            "time": "2015-03-01T00:16:20+00:00",
            "price": "0.003926827277291318",
            "baseAmount": 128.95156374260318,
            "counterAmount": 0.506370517953824,
            "account": "rUBLCjWdsPPMkppdFXVJWhHnr3FNqCzgG3",
            "counterparty": "r4rCiFc9jpMeCpKioVJUMbT1hU4kj3XiSt",
            "tx_hash": "7257EC2FB029E76003B771755448334B650E376312B99AEF7F6B8DC85BF50C48",
            "ledgerIndex": 11991162
        },
        {
            "time": "2015-03-01T00:16:50+00:00",
            "price": "0.003928013992378335",
            "baseAmount": 271.64872683,
            "counterAmount": 1.06704,
            "account": "rUBLCjWdsPPMkppdFXVJWhHnr3FNqCzgG3",
            "counterparty": "rBxy23n7ZFbUpS699rFVj1V9ZVhAq6EGwC",
            "tx_hash": "57996435CAF193F427408187F4DE72879E76015E446D78C7C5702D8F193B478F",
            "ledgerIndex": 11991168
        },
        {
            "time": "2015-03-01T00:18:00+00:00",
            "price": "0.003958567143537345",
            "baseAmount": 12.608369653599198,
            "counterAmount": 0.04991107784431131,
            "account": "rDVBvAQScXrGRGnzrxRrcJPeNLeLeUTAqE",
            "counterparty": "r9bf8V4ae5xReYnKPXgnwERDFPoW34FhGy",
            "tx_hash": "5B1AEFDC4AF56843854CACEE885B856273F260F9DA5990600651F06B913136AB",
            "ledgerIndex": 11991181
        },
        {
            "time": "2015-03-01T00:18:00+00:00",
            "price": "0.003958567143537345",
            "baseAmount": 54.95776227293271,
            "counterAmount": 0.21755399201596803,
            "account": "rDVBvAQScXrGRGnzrxRrcJPeNLeLeUTAqE",
            "counterparty": "rfZ4YjC4CyaKFx9cgzYNKk4E2zTXRJif26",
            "tx_hash": "139159A556F7F240078D378F3FCF556D01EF2C99DB79DD84338E7AD71419EEA6",
            "ledgerIndex": 11991181
        },
        {
            "time": "2015-03-01T00:18:00+00:00",
            "price": "0.003958567143537345",
            "baseAmount": 91.90007712981681,
            "counterAmount": 0.3637926258146406,
            "account": "rDVBvAQScXrGRGnzrxRrcJPeNLeLeUTAqE",
            "counterparty": "rEiUs9rEiGHmpaprkYDNyXnJYg4ANxWLy9",
            "tx_hash": "10E7823DFE7B2F4EAD204A5FA212DCE9624FD87AA5B45E29AE21C2BFCC797CD8",
            "ledgerIndex": 11991181
        }
    ]
}

The format of the response depends on the format and reduce parameters from the request. See Response Formats for details.

If results are reduced (the default), then each result represents an interval of time, with the following attributes, in order:

Field	Value	Description
startTime	String (Date-Time)	The start time of this interval.
baseVolume	Number	Total amount of the base currency traded in this interval.
counterVolume	Number	Total amount of the counter currency traded in this interval.
count	Number	Number of trades in this interval.
open	Number	Price of the first trade in this interval.
high	Number	Highest price traded in this interval. (Most counter currency received per unit of base currency spent.)
low	Number	Lowest price traded in this interval. (Least counter currency received per unit of base currency spent.)
close	Number	Price of the last trade in this interval.
vwap	Number	Volume weighted average price of trades in this interval.
openTime	String (Date-Time)	The time at which the first trade in this interval occurred.
closeTime	String (Date-Time)	The time at which the last trade in this interval occurred.
partial	Boolean	If true, this row may not include all trades in the interval due to the alignment of the requested time period. For example, a time interval of 1 minute was requested, but the end time for the range was 3:45:30.

All prices are represented as the amount of the counter currency received for each unit of the base-currency spent.

The time of an exchange is defined as the close time of the ledger that contained the transaction exercising the exchange.

Note: The API omits intervals during which no exchanges occurred. This means that the rows may not be sequential. (They are in order, but with gaps for empty intervals.)

If the results are not reduced (the request used "reduce":false), then each result represents an individual transaction that caused a currency exchange, with the following attributes:

Field	Value	Description
time	String (Date-Time)	The time this transaction occurred, as defined by the close time of the ledger that included it.
price	Number	The amount of the counter currency received for each unit of the base-currency spent in this trade.
baseAmount	Number	Total amount of the base currency spent in this trade.
counterAmount	Number	Total amount of the counter currency received in this trade.
account	String	The Ripple address of the account providing the base currency.
counterparty	String	The Ripple address of the account providing the counter currency.
tx_hash	String	The identifying hash of the transaction where this transaction occurred.
ledgerIndex	Number	The sequence number of the ledger that included this transaction.

17 KiB Raw Blame History

Ripple Charts API

Architecture

Components

Ledger Importer

Data Store

API Server

Memory Cache

Setup

Start API Service

Start Ledger Importer

API Objects

Dates and Times

Currency Objects

Response Formats

API Method Reference

offers_exercised

Response Format

17 KiB

Raw Blame History