ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-22 12:45:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #454 from mDuo13/data_api_deprecations

Browse Source 
Update Data API docs for v2.3.5
This commit is contained in:
Rome Reginelli
2018-09-06 11:43:48 -07:00
committed by GitHub
parent 8ceb66b812 4ca5761df5
commit cf9af7f8d8
1 changed files with 17 additions and 282 deletions
Download Patch File Download Diff File Expand all files Collapse all files

299
content/references/data-api.md
View File

@@ -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. <!-- STYLE_OVERRIDE: time period --> 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]<br>](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
<!-- MULTICODE_BLOCK_START -->
*REST*
```
GET /v2/capitaliztion/{currency}
```
<!-- MULTICODE_BLOCK_END -->
[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]<br>](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]<br>](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
<!-- MULTICODE_BLOCK_START -->
*REST*
```
GET /v2/network/issued_value
```
<!-- MULTICODE_BLOCK_END -->
[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]<br>](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