Warning
The YCharts API is available to our API customers for their internal use only. Any redistribution or commercial use of data from the API is strictly prohibited without prior written consent from YCharts. For more details on our API’s capabilities and pricing please contact sales@ycharts.com or call (866) 965-7552.
Custom Security Series¶
The Custom Security Data Series Endpoint is used to obtain a series of date-value pairs
of data from one or more custom securities for one or more calculations. It takes
optional start_date
and end_date
parameters and will return all values
between the requested dates. It also accepts a number of optional parameters for
series resampling and aggregation.
Note
Full list of calcs can be found in the Reference Guide
Request Info¶
Request Method |
GET |
URL |
/api/v3/custom_securities/ |
Request Parameters¶
Parameter |
Required |
Description |
---|---|---|
security_id[s] |
Y |
The security id (e.g. ‘Y:1234’) for a custom security, or a comma separated list of security ids |
calc[s] |
Y |
The code for a calculation, or a comma separated list of calculations |
start_date |
N |
The first date of the desired date range, defaults to one day ago |
end_date |
N |
The last date of the desired data range, defaults to today |
resample_frequency |
N |
This value specifies the desired resampling frequency of each series in the response. |
resample_function |
N |
The operation used to resample data. |
fill_method |
N |
This value specifies the mechanism by which null values in the response are handled. |
aggregate_function |
N |
The operation used to return a single-value statistic per calc series in the response. |
use_estimates |
N |
Uses estimate data for the provided calcs when available. (true or false) |
force_date_range |
N |
A resampling parameter that pegs series response data to the supplied date range. (true or false) |
Note
There is a maximum of 100 custom securities per request.
There is a maximum of 100 calculations per request.
resample_frequency
andresample_function
must be specified together.See our API Reference Guide for a complete list of parameter value options.
Tip
The code for a calculation can be found in the url of the custom security’s historical data page. For example, the level of Y:1234 is found at https://ycharts.com/custom_securities/1234/level
Response Info¶
The response will contain one or more custom security objects. The key for each custom security object is the security id passed in the request.
Field |
Type |
Description |
---|---|---|
meta |
Meta |
This object contains information about the query for the custom security object |
results |
Results |
This object contains one or more calculation data objects. The key for each object is the code for the calculation. |
Field |
Type |
Description |
---|---|---|
data |
Array |
An array of arrays, each containing a date-value pair |
meta |
Meta |
This object contains information about the query for the data |
Examples¶
The following is an example successful request with relative dates
Request URL
https://ycharts.com/api/v3/custom_securities/Y:1234/series/level?start_date=-60&end_date=-50
Response
{
"meta": {
"status": "ok",
"url": "http://ycharts.com/api/v3/custom_securities/Y:1234/series/level?start_date=-60&end_date=-50"
},
"response": {
"Y:1234": {
"meta": {
"status": "ok"
},
"results": {
"level": {
"data": [
["2014-12-29", 113000.00],
["2014-12-30", 112000.00],
["2014-12-31", 110000.00],
["2015-01-02", 109000.00],
["2015-01-05", 106000.00],
["2015-01-06", 106000.00],
["2015-01-07", 107000.00]
],
"meta": {
"status": "ok"
}
}
}
}
}
}
The following is an example successful request with multiple calculations and absolute dates
Request URL
https://ycharts.com/api/v3/custom_securities/Y:1234/series/level,ytd_total_return?start_date=2014-01-03&end_date=2014-01-13
Response
{
"meta": {
"status": "ok",
"url": "http://ycharts.com/api/v3/custom_securities/Y:1234/series/level,ytd_total_return?start_date=2014-01-03&end_date=2014-01-13"
},
"response": {
"Y:1234": {
"meta": {
"status": "ok"
},
"results": {
"level": {
"data": [
["2014-01-03", 770000.00],
["2014-01-06", 770000.00],
["2014-01-07", 770000.00],
["2014-01-08", 770000.00],
["2014-01-09", 760000.00],
["2014-01-10", 760000.00],
["2014-01-13", 760000.00]
],
"meta": {
"status": "ok"
}
},
"ytd_total_return": {
"data": [
["2014-01-03", 0.4129],
["2014-01-06", 0.486],
["2014-01-07", 0.3895],
["2014-01-08", 0.4744],
["2014-01-09", 0.3023],
["2014-01-10", 0.2136],
["2014-01-13", 0.2827]
],
"meta": {
"status": "ok"
}
}
}
}
}
}
The following is an example successful request with multiple custom securities
Request URL
https://ycharts.com/api/v3/custom_securities/Y:1234,Y:5678/series/level?start_date=-60&end_date=-50
Response
{
"meta": {
"status": "ok",
"url": "http://ycharts.com/api/v3/custom_securities/Y:1234,Y:5678/series/level?start_date=-60&end_date=-50"
},
"response": {
"Y:1234": {
"meta": {
"status": "ok"
},
"results": {
"level": {
"data": [
["2014-12-29", 113000.00],
["2014-12-30", 112000.00],
["2014-12-31", 110000.00],
["2015-01-02", 109000.00],
["2015-01-05", 106000.00],
["2015-01-06", 106000.00],
["2015-01-07", 107000.00]
],
"meta": {
"status": "ok"
}
}
}
},
"Y:5678": {
"meta": {
"status": "ok"
},
"results": {
"level": {
"data": [
["2014-12-29", 470000.00],
["2014-12-30", 470000.00],
["2014-12-31", 460000.00],
["2015-01-02", 460000.00],
["2015-01-05", 460000.00],
["2015-01-06", 450000.00],
["2015-01-07", 460000.00]
],
"meta": {
"status": "ok"
}
}
}
}
}
}
The following is an example of an incorrect request with invalid relative dates
Request URL
https://ycharts.com/api/v3/custom_securities/Y:1234,Y:5678/series/level?start_date=-60&end_date=-dsd
Response
{
"meta": {
"error_code": 400,
"error_message": "Invalid end date format.",
"status": "error",
"url": "http://ycharts.com/api/v3/custom_securities/Y:1234,Y:5678/series/level?start_date=-60&end_date=-dsd"
},
"response": {}
}
The following is an example of an incorrect request that requests a custom security Y:0000 that does not exist
Request URL
https://ycharts.com/api/v3/custom_securities/Y:1234,Y:0000/series/level?start_date=-60&end_date=-50
Respose
{
"meta": {
"status": "ok",
"url": "http://ycharts.com/api/v3/custom_securities/Y:1234,Y:0000/series/level?start_date=-60&end_date=-50"
},
"response": {
"Y:1234": {
"meta": {
"status": "ok"
},
"results": {
"level": {
"data": [
["2014-12-29", 113000.00],
["2014-12-30", 112000.00],
["2014-12-31", 110000.00],
["2015-01-02", 109000.00],
["2015-01-05", 106000.00],
["2015-01-06", 106000.00],
["2015-01-07", 107000.00]
],
"meta": {
"status": "ok"
}
}
}
},
"Y:0000": {
"meta": {
"error_code": 404,
"error_message": "Symbol Not Found.",
"status": "error"
}
}
}
}
The following is an example of an incorrect request, which contains an error in the calculation
Request URL
https://ycharts.com/api/v3/custom_securities/Y:1234,Y:5678/points/levl?start_date=2014-01-03&end_date=2014-01-13
Response
{
"meta": {
"status": "ok",
"url": "http://ycharts.com/api/v3/custom_securities/Y:1234,Y:5678/series/levl?start_date=2014-01-03&end_date=2014-01-13"
},
"response": {
"Y:1234": {
"meta": {
"status": "ok"
},
"results": {
"levl": {
"meta": {
"error_code": 404,
"error_message": "Calc Not Found.",
"status": "error"
}
}
}
},
"Y:5678": {
"meta": {
"status": "ok"
},
"results": {
"levl": {
"meta": {
"error_code": 404,
"error_message": "Calc Not Found.",
"status": "error"
}
}
}
}
}
}
The following is an example successful request with resampling parameters
Request URL
https://ycharts.com/api/v3/custom_securities/Y:1234/series/level?start_date=2014-01-01&end_date=2014-03-01&resample_frequency=monthly&resample_function=min
Response
{
"meta": {
"status": "ok",
"url": "http://ycharts.com/api/v3/custom_securities/Y:1234/series/level?start_date=2014-01-01&end_date=2014-03-01&resample_frequency=monthly&resample_function=min"
},
"response": {
"Y:1234": {
"meta": {
"status": "ok"
},
"results": {
"level": {
"data": [
["2014-01-31", 113000.00],
["2014-02-28", 112000.00],
["2014-03-31", 110000.00]
],
"meta": {
"status": "ok"
}
}
}
}
}
}