diff --git a/content/references/data-api.md b/content/references/data-api.md index f04716a5c0..e5d08a0d43 100644 --- a/content/references/data-api.md +++ b/content/references/data-api.md @@ -25,6 +25,7 @@ The Ripple Data API v2 replaces the Historical Database v1 and the [Charts API]( [v2.2.0]: https://github.com/ripple/rippled-historical-database/releases/tag/v2.2.0 [v2.3.0]: https://github.com/ripple/rippled-historical-database/releases/tag/v2.3.0 [v2.3.2]: https://github.com/ripple/rippled-historical-database/releases/tag/v2.3.2 +[v2.3.5]: https://github.com/ripple/rippled-historical-database/releases/tag/v2.3.5 # API Method Reference @@ -42,11 +43,9 @@ Ledger Contents Methods: * [Normalize - `GET /v2/normalize`](#normalize) * [Get Daily Reports - `GET /v2/reports/`](#get-daily-reports) * [Get Stats - `GET /v2/stats/`](#get-stats) -* [Get Capitalization - `GET /v2/capitalization/{currency}`](#get-capitalization) * [Get Active Accounts - `GET /v2/active_accounts/{base}/{counter}`](#get-active-accounts) * [Get Exchange Volume - `GET /v2/network/exchange_volume`](#get-exchange-volume) * [Get Payment Volume - `GET /v2/network/payment_volume`](#get-payment-volume) -* [Get Issued Value - `GET /v2/network/issued_value`](#get-issued-value) * [Get External Markets - `GET /v2/network/external_markets`](#get-external-markets) * [Get XRP Distribution - `GET /v2/network/xrp_distribution`](#get-xrp-distribution) * [Get Top Currencies - `GET /v2/network/top_currencies`](#get-top-currencies) @@ -633,38 +632,25 @@ Optionally, you can provide the following query parameters: |:-------------|:-----------------------|:-------------------------------------| | `start` | String - [Timestamp][] | Filter results to this time and later. | | `end` | String - [Timestamp][] | Filter results to this time and earlier. | -| `interval` | String | If provided and `currency` is also specified, return results aggregated into intervals of the specified length instead of individual payments. Valid intervals are `day`, `week`, or `month`. | | `descending` | Boolean | If `true`, return results in reverse chronological order. The default is `false`. | | `limit` | Integer | Maximum results per page. The default is 200. Cannot be more than 1000. | | `marker` | String | [Pagination](#pagination) key from previously returned response. | | `format` | String | Format of returned results: `csv` or `json`. The default is `json`. | +The `interval` parameter for aggregated results has been removed as of [v2.3.5][]. #### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: -| Field | Value | Description | -|:-----------|:-------------------------------------------------------------|:--| -| `result` | String | The value `success` indicates that this is a successful response. | -| `count` | Integer | Number of payments returned. | -| `marker` | String | (May be omitted) [Pagination](#pagination) marker. | -| `payments` | Array of [Payment Objects][], or array of aggregate objects. | The requested payments. | +| Field | Value | Description | +|:-----------|:-----------------------------|:---------------------------------| +| `result` | String | The value `success` indicates that this is a successful response. | +| `count` | Integer | Number of payments returned. | +| `marker` | String | (May be omitted) [Pagination](#pagination) marker. | +| `payments` | Array of [Payment Objects][] | The requested payments. | -##### Aggregate Results - -If the request specifies a `currency` and an `interval`, the result includes objects summarizing activity over a specific time period instead of listing individual payments. Each interval summary object has the following fields: - -| Field | Value | Description | -|:-----------------|:-----------------------|:---------------------------------| -| `count` | Number | The number of payments that occurred during this interval. | -| `currency` | String - Currency Code | This summary describes payments that delivered the specified currency. | -| `issuer` | String - Address | (Omitted for XRP) This summary describes payments that delivered the currency issued by this address. | -| `start` | String - [Timestamp][] | The start time of this interval. | -| `total_amount` | Number | The amount of the `currency` delivered during this interval. | -| `average_amount` | Number | The average amount of currency delivered by a single payment during this interval. | - #### Example Request: @@ -1282,133 +1268,6 @@ Response: - -## Get Capitalization -[[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/capitalization.js "Source") - -Get the total amount of a single currency issued by a single issuer, also known as the [market capitalization](https://en.wikipedia.org/wiki/Market_capitalization). _(New in [v2.0.4][])_ - -#### Request Format - - - -*REST* - -``` -GET /v2/capitaliztion/{currency} -``` - - - -[Try it! >](data-api-v2-tool.html#get-capitalization) - -This method requires the following URL parameters: - -| Field | Value | Description | -|:-----------|:-------|:-------------------------------------------------------| -| `currency` | String | Currency to look up, in the form of [currency](#currency-code)+[issuer](#addresses). XRP is disallowed. | - - -Optionally, you can provide the following query parameters: - -| Field | Value | Description | -|:-------------|:-----------------------|:-------------------------------------| -| `start` | String - [Timestamp][] | Start time of query range. The default is `2013-01-01T00:00:00Z`. | -| `end` | String - [Timestamp][] | End time of query range. The default is the current time. | -| `interval` | String | Aggregation interval - `day`, `week`, or `month`. The default is `day`. | -| `limit` | Integer | Maximum results per page. The default is 200. Cannot be more than 1000. | -| `marker` | String | [Pagination](#pagination) key from previously returned response. | -| `descending` | Boolean | If `true`, return results in reverse chronological order. The default is `false`. | -| `adjusted` | Boolean | If `true`, do not count known issuer-owned addresses towards market capitalization. The default is `true`. | -| `format` | String | Format of returned results: `csv` or `json`. The default is `json`. | - -If the request omits both `start` and `end`, the API returns only the most recent sample. - - -#### Response Format -A successful response uses the HTTP code **200 OK** and has a JSON body with the following: - -| Field | Value | Description | -|:-----------|:---------------------------------------|:-----------------------| -| `result` | String | The value `success` indicates that this is a successful response. | -| `count` | Integer | Number of reports returned. | -| `currency` | String | Currency requested. | -| `issuer` | String | Issuer requested. | -| `marker` | String | (May be omitted) [Pagination](#pagination) marker. | -| `rows` | Array of issuer capitalization objects | The requested capitalization data. | - -Each **issuer capitalization object** has the following fields: - -| Field | Value | Description | -|:---------|:-----------------------|:-----------------------------------------| -| `date` | String - [Timestamp][] | The start time of the interval this object represents. | -| `amount` | [String - Number][] | The total amount of currency issued by the issuer as of the start of this interval. | - -#### Example - -Request: - -``` -GET /v2/capitalization/USD+rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q?start=2015-01-01T00:00:00Z&end=2015-10-31&interval=month -``` - -Response: - -``` -200 OK -{ - "result": "success", - "currency": "USD", - "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", - "count": 10, - "rows": [ - { - "date": "2015-01-01T00:00:00Z", - "amount": "4212940.254176095" - }, - { - "date": "2015-02-01T00:00:00Z", - "amount": "5102817.663782776" - }, - { - "date": "2015-03-01T00:00:00Z", - "amount": "4179270.8503426993" - }, - { - "date": "2015-04-01T00:00:00Z", - "amount": "2609239.954946732" - }, - { - "date": "2015-05-01T00:00:00Z", - "amount": "2262976.3681027396" - }, - { - "date": "2015-06-01T00:00:00Z", - "amount": "2401904.277326213" - }, - { - "date": "2015-07-01T00:00:00Z", - "amount": "2007614.760195671" - }, - { - "date": "2015-08-01T00:00:00Z", - "amount": "2286058.6013003727" - }, - { - "date": "2015-09-01T00:00:00Z", - "amount": "2070512.4729615194" - }, - { - "date": "2015-10-01T00:00:00Z", - "amount": "2140238.7719266433" - } - ] -} -``` - - - - ## Get Active Accounts [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/activeAccounts.js "Source") @@ -1586,16 +1445,13 @@ Optionally, you can provide the following query parameters: | Field | Value | Description | |:--------------------|:---------------------------|:--------------------------| -| `start` | String - [Timestamp][] | Start time of query range. The default is the start of the most recent interval. | -| `end` | String - [Timestamp][] | End time of query range. The default is the end of the most recent interval. | -| `interval` | String | Aggregation interval - valid intervals are `day`, `week`, or `month`. The default is `day`. | -| `live` | String | Return a live rolling window of this length of time. Valid values are `day`, `hour`, or `minute`. Ignored if `interval` is provided. _(New in [v2.3.0][])_ | +| `live` | String | Return a live rolling window of this length of time. Valid values are `day`, `hour`, or `minute`. _(New in [v2.3.0][])_ | | `exchange_currency` | String - [Currency Code][] | Normalize all amounts to use this as a display currency. If not XRP, `exchange_issuer` is also required. The default is XRP. | | `exchange_issuer` | String - [Address][] | Normalize results to the specified `currency` issued by this issuer. | -| `limit` | Integer | Maximum results per page. The default is 200. Cannot be more than 1000. | -| `marker` | String | [Pagination](#pagination) key from previously returned response. | | `format` | String | Format of returned results: `csv` or `json`. The default is `json`. | +The `start`, `end`, `interval`, `limit`, and `marker` parameters have been removed in [v2.3.5][]. + #### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -1736,16 +1592,13 @@ Optionally, you can provide the following query parameters: | Field | Value | Description | |:--------------------|:---------------------------|:--------------------------| -| `start` | String - [Timestamp][] | Start time of query range. The default is the start of the most recent interval. | -| `end` | String - [Timestamp][] | End time of query range. The default is the end of the most recent interval. | -| `interval` | String | Aggregation interval - valid intervals are `day`, `week`, or `month`. The default is `day`. | -| `live` | String | Return a live rolling window of this length of time. Valid values are `day`, `hour`, or `minute`. Ignored if `interval` is provided. _(New in [v2.3.0][])_ | +| `live` | String | Return a live rolling window of this length of time. Valid values are `day`, `hour`, or `minute`. _(New in [v2.3.0][])_ | | `exchange_currency` | String - [Currency Code][] | Normalize all amounts to use this as a display currency. If not XRP, `exchange_issuer` is also required. The default is XRP. | | `exchange_issuer` | String - [Address][] | Normalize results to the specified `currency` issued by this issuer. | -| `limit` | Integer | Maximum results per page. The default is 200. Cannot be more than 1000. | -| `marker` | String | [Pagination](#pagination) key from previously returned response. | | `format` | String | Format of returned results: `csv` or `json`. The default is `json`. | +The `start`, `end`, `interval`, `limit`, and `marker` parameters have been removed in [v2.3.5][]. + #### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -1842,115 +1695,6 @@ Response: -## Get Issued Value -[[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getMetric.js "Source") - -Get the total value of all currencies issued by major gateways over time. By default, returns only the most recent measurement. _(New in [v2.0.4][])_ - -The API returns results in units of a single _display currency_ rather than many different currencies. The conversion uses standard rates to and from XRP. - -#### Request Format - - - -*REST* - -``` -GET /v2/network/issued_value -``` - - - -[Try it! >](data-api-v2-tool.html#get-issued-value) - -Optionally, you can provide the following query parameters: - -| Field | Value | Description | -|:--------------------|:---------------------------|:--------------------------| -| `start` | String - [Timestamp][] | Start time of query range. The default is the start of the most recent interval. | -| `end` | String - [Timestamp][] | End time of query range. The default is the end of the most recent interval. | -| `exchange_currency` | String - [Currency Code][] | Normalize all amounts to use this as a display currency. If not XRP, `exchange_issuer` is also required. The default is XRP. | -| `exchange_issuer` | String - [Address][] | Normalize results to the specified `currency` issued by this issuer. | -| `limit` | Integer | Maximum results per page. The default is 200. Cannot be more than 1000. | -| `marker` | String | [Pagination](#pagination) key from previously returned response. | -| `format` | String | Format of returned results: `csv` or `json`. The default is `json`. | - -#### Response Format - -A successful response uses the HTTP code **200 OK** and has a JSON body with the following: - -| Field | Value | Description | -|:---------|:------------------------------|:----------------------------------| -| `result` | String | The value `success` indicates that this is a successful response. | -| `count` | Integer | Number of results returned. | -| `rows` | Array of Issued Value Objects | Aggregated capitalization at the requested point(s) in time. | - -Each **Issued Value Object** represents the total value issued at one point in time, and has the following fields: - -| Field | Value | Description | -|:----------------|:-----------------------|:----------------------------------| -| `components` | Array of Objects | The data on individual issuers that was used to assemble this total. | -| `exchange` | Object | Indicates the display currency used, as with fields `currency` and (except for XRP) `issuer`. All amounts are normalized by first converting to XRP, and then to the display currency specified in the request. | -| `exchange_rate` | Number | The exchange rate to the displayed currency from XRP. | -| `time` | String - [Timestamp][] | When this data was measured. | -| `total` | Number | Total value of all issued assets at this time, in units of the display currency. | - -#### Example - -Request: - -``` -GET /v2/network/issued_value?start=2015-10-01T00:00:00&end=2015-10-01T00:00:00&exchange_currency=USD&exchange_issuer=rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q -``` - -Response: - -``` -200 OK -{ - "result": "success", - "count": 1, - "rows": [ - { - "components": [ - { - "currency": "USD", - "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", - "amount": "2177473.2843876695", - "rate": "0.000028818194", - "converted_amount": "2166521.1303508882" - }, - { - "currency": "USD", - "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", - "amount": "1651297.315492664", - "rate": "0.000028888001", - "converted_amount": "1639021.4313562333" - }, - - ... (additional results trimmed for size) ... - - { - "currency": "MXN", - "issuer": "rG6FZ31hDHN1K5Dkbma3PSB5uVCuVVRzfn", - "amount": "2288827.2376308907", - "rate": "0.00050850375", - "converted_amount": "129061.20018881827" - } - ], - "exchange": { - "currency": "USD", - "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q" - }, - "total": "8338101.394233938", - "exchange_rate": "0.0053547404", - "date": "2015-10-01T00:00:00Z" - } - ] -} -``` - - ## Get External Markets [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/externalMarkets.js "Source") @@ -3757,14 +3501,14 @@ Optionally, you can provide the following query parameters: |:-------------|:-----------------------|:-------------------------------------| | `start` | String - [Timestamp][] | Start time of query range. | | `end` | String - [Timestamp][] | End time of query range. | -| `interval` | String | Aggregation interval (`hour`,`day`,`week`). If omitted, return individual accounts. Not compatible with the `parent` parameter. | | `limit` | Integer | Maximum results per page. The default is 200. Cannot be more than 1,000. | | `marker` | String | [Pagination](#pagination) key from previously returned response. | | `descending` | Boolean | If `true`, return results in reverse chronological order. The default is `false`. | | `parent` | String | Filter results to children of the specified parent account. Not compatible with the `interval` parameter. | -| `reduce` | Boolean | Return a count of results only. | | `format` | String | Format of returned results: `csv` or `json`. The default is `json`. | +The `interval` and `reduce` parameters have been removed in [v2.3.5][]. + #### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -3773,16 +3517,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `result` | String | The value `success` indicates that this is a successful response. | | `count` | Integer | Number of accounts returned. | | `marker` | String | (May be omitted) [Pagination](#pagination) marker. | -| `accounts` | Array | If the request used the `interval` query parameter, each member of the array is an interval object. Otherwise, this field is an array of [account creation objects](#account-creation-objects). | - -##### Interval Objects - -If the request uses the `interval` query parameter, the response has an array of interval objects, each of which represents the number of accounts created during a single interval. Interval objects have the following fields: - -| Field | Value | Description | -|:--------|:---------------------|:--------------------------------------------| -| `date` | String - [Timestamp] | When this interval starts. (The length of the interval is determined by the request.) | -| `count` | Number | How many accounts were created in this interval. | +| `accounts` | Array |An array of [account creation objects](#account-creation-objects). | #### Example