diff --git a/content/data_v2.md b/content/data_v2.md index 965cb60c61..18788cabb6 100644 --- a/content/data_v2.md +++ b/content/data_v2.md @@ -19,7 +19,7 @@ General Methods: * [Get Transaction - `GET /v2/transactions/{:hash}`](#get-transaction) * [Get Transactions - `GET /v2/transactions/`](#get-transactions) * [Get Exchanges - `GET /v2/exchanges/:base/:counter`](#get-exchanges) -* [Get Reports - `GET /v2/reports/`](#get-reports) +* [Get Daily Summary - `GET /v2/reports/`](#get-daily-summary) * [Get Stats - `GET /v2/stats/`](#get-stats) Account Methods: @@ -104,6 +104,8 @@ An account creation object represents the action of creating an account in the R An exchange object represents an actual exchange of currency, which can occur in the Ripple Consensus Ledger as the result of executing either an OfferCreate transaction or a Payment transaction. In order for currency to actually change hands, there must be a previously-unfilled Offer previously placed in the ledger with an OfferCreate transaction. +A single transaction can cause several exchanges to occur. In this case, the sender of the transaction is the taker for all the exchanges, but each exchange will have a different provider, currency pair, or both. + | Field | Value | Description | |-------|-------|-------------| | base\_amount | Number | The amount of the base currency that was traded | @@ -122,6 +124,8 @@ An exchange object represents an actual exchange of currency, which can occur in ## Reports Objects ## +Reports objects show the activity of a given account over a specific interval of time, typically a day. Reports have the following fields: + | Field | Value | Description | |-------|-------|-------------| | account | String - Address | One account worth of activity | @@ -137,6 +141,44 @@ An exchange object represents an actual exchange of currency, which can occur in | total\_value\_sent | Number | +## Payment Objects ## + +In the Data API, a Payment Object represents an event where one account sent value to another account. This mostly lines up with Ripple transactions of the `Payment` transaction type, except that the Data API does not consider a transaction to be a payment if the sending `Account` and the `Destination` account are the same, or if the transaction failed. + +Payment objects have the following fields: + +| Field | Value | Description | +|-------|-------|-------------| +| amount | String - Number | The amount of the destination `currency` that the transaction was instructed to send. In the case of Partial Payments, this is a "maximum" amount. | +| delivered\_amount | String - Number | The amount of the destination `currency` actually received by the destination account. | +| destination\_balance\_changes | Array | Array of [balance change objects][], indicating all changes made to the `destination` account's balances. | +| source\_balance\_changes | Array | Array of [balance change objects][], indicating all changes to the `source` account's balances (except the XRP transaction cost). | +| fee | String - Number | The amount of XRP spent by the `source` account on the transaction cost. | +| currency | String - Currency Code | The currency that the `destination` account received. | +| destination | String - Address | The account that received the payment. | +| executed\_time | String - ISO 8601 UTC Timestamp | The time the ledger that included this payment closed. | +| ledger\_index | Number - Ledger Index | The sequence number of the ledger that included this payment. | +| source | String - Address | The account that sent the payment. | +| source\_currency | String - Currency Code | The currency that the `source` account spent. | +| tx\_hash | String - Hash | The identifying hash of the transaction that caused the payment. | + +[balance change objects]: #balance-change-objects + +### Balance Change Objects ### + +Balance change objects represent a single balance change that occurs in transaction execution. Every balance change object is associated with a Ripple account. A single Ripple transaction may cause changes to balances with several counterparties, as well as changes to XRP. + +Balance Change Objects have the following fields: + +| Field | Value | Description | +|-------|-------|-------------| +| counterparty | String - Address | The counterparty, or issuer, of the `currency`. In the case of XRP, this is an empty string. | +| currency | String - Currency Code | The currency for which this balance changed. | +| value | String - Number | The amount of the `currency` that the associated account gained or lost. This value can be positive (for amounts gained) or negative (for amounts lost). | + + + + # API Reference # ## Get Ledgers ## @@ -811,7 +853,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the -## Get Reports ## +## Get Daily Summary ## [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routesV2/reports.js "Source") Retrieve per account per day aggregated payment summaries @@ -860,7 +902,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the ## Get Stats ## [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routesV2/stats.js "Source") -Retrieve ripple network transaction stats +Retrieve statistics about transaction activity in the Ripple Consensus Ledger, divided into intervals of time. #### Request Format #### @@ -870,23 +912,17 @@ Retrieve ripple network transaction stats ``` GET /v2/stats -GET /v2/stats/{:family} -GET /v2/stats/{:family}/{:metric} ``` -This method requires the following URL parameters: - -| Field | Value | Description | -|--------|-------|-------------| -| family | String | Return only specified family (`type`, `result`, or `metric`) | -| metric | String | Return only a specific metric from the family subset What metrics can you choose? | Optionally, you can also include the following query parameters: | Field | Value | Description | |------------|---------|-------------| +| family | String | If provided, filter results to a single family of stats: `type`, `result`, or `metric`. By default, provides all stats from all families. | +| metrics | String | Filter results to one or more metrics (in a comma-separated list). Requires the `family` of the metrics to be specified. By default, provides all metrics in the family. | | start | String | UTC start time of query range | | end | String | UTC end time of query range | | interval | String | Aggregation interval (`hour`,`day`,`week`, defaults to `day`) | @@ -895,6 +931,16 @@ Optionally, you can also include the following query parameters: | descending | Boolean | Reverse chronological order | | format | String | Format of returned results: `csv`,`json` defaults to `json` | +##### Families and Metrics ##### + +The `family` and `metrics` query parameters provide a way to filter results to a specific subset of all metrics available for transactions in any given interval. Each metric is tied to a specific family, as follows: + +| Family | Included Metrics | Meaning | +|--------|------------------|---------| +| type | All Ripple transaction types, including `Payment`, `AccountSet`, `SetRegularKey`, `OfferCreate`, `OfferCancel`, `TrustSet`. | Number of transactions of the given type that occurred during the interval. | +| result | All [transaction result codes](transactions.html#transaction-results) (string codes, not the numeric codes), including `tesSUCCESS`, `tecPATH_DRY`, and many others. | Number of transactions that resulted in the given code during the interval. | +| metric | Data-API defined [transaction metrics](#transaction-metrics). | (Varies) | + #### Response Format #### A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -903,9 +949,23 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | result | `success` | Indicates that the body represents a successful response. | | count | Integer | Number of reports returned. | | marker | String | Pagination marker | -| stats | Array of stats objects | The requested stats | +| stats | Array of stats objects | The requested stats. Omits metrics with a value of 0, and intervals that have no nonzero metrics. | +#### Transaction Metrics #### + +The Data API automatically calculates the following metrics for every interval: + +| Field | Value | Description | +|--------|-------|-------------| +| accounts\_created | Number | The number of new accounts funded during this interval. | +| exchanges\_count | Number | The number of currency exchanges that occurred during this interval. | +| ledger\_count | Number | The number of ledgers closed during this interval. | +| ledger\_interval | Number | The average number of seconds between ledgers closing during this interval. | +| payments\_count | Number | The number of payments from one account to another during this interval. | +| tx\_per\_ledger | Number | The average number of transactions per ledger in this interval. | + +If any of the metrics have a value of 0, they are omitted from the results. ## Get Accounts ## diff --git a/js/apitool-methods-data_v2.js b/js/apitool-methods-data_v2.js index 28a44375c7..e347c177a7 100644 --- a/js/apitool-methods-data_v2.js +++ b/js/apitool-methods-data_v2.js @@ -56,17 +56,27 @@ Request('Get Exchanges', { } }); -Request('Get Reports', { +Request('Get Daily Summary', { method: GET, path: "/v2/reports/{:date}?{:query_params}", description: "Retrieve an aggregated summary of payments per account for one day.", - link: "#get-reports", + link: "#get-daily-summary", params: { "{:date}": "2015-08-19T00:00:00Z", "{:query_params}": "accounts=true&payments=true" } }); +Request('Get Stats', { + method: GET, + path: "/v2/stats/?{:query_params}", + description: "Retrieve an aggregated summary of payments per account for one day.", + link: "#get-daily-summary", + params: { + "{:query_params}": "family=metric&metrics=accounts_created,exchanges_count,ledger_count,payments_count" + } +}); + // account methods -----------------------------------// Request("ACCOUNT METHODS");