Introducing
Aggregate Data API Improvements
Nov 25, 2020
We have been working on improving our Aggregate Pricing Data APIs and with that comes some corrections to existing behavior. The biggest change is how we handle the timespan parameters
from
and
to
respective to the aggregate rollup parameters
multiplier
and
resolution
. This article begins by explaining some existing behavior that has not changed, then leads into the timespan changes.
Tl;dr
The time parameter behavior has been changed to be simpler and matches our original intent of the API. Try out this new behavior before it releases at
https://api.polygon.io/vX/aggs/ticker/{ticker}/range/{multiplier}/{resolution}/{from}/{to}
. The new behavior is planned to release Friday December, 4th 2020 at 5pm ET for stocks, TBD for crypto and fx.
Clarifications
Query Parameters
Limit
You can pass the
limit
query parameter to any of the agg endpoints where
limit
has a default value of
5,000
and a max value of
50,000
. This parameter will limit the number of
base aggregate bars that are used to generate the final result.
Our base aggregates are minute and daily bars, while a request for any other resolution results in those bars being calculated from one of the base aggregates.
The following illustrates the mappings of requested resolutions to their corresponding base aggregate.
| Minute | Day |
|---|
| Minute, Hour | Day, Week, Month, Quarter, Year |
Example
A request with a multiplier
1
and resolution
hour
that spans from 2pm to 4pm will cover 120 base minute bars, but return 2 1-hour bars, one for 2pm-3pm and one for 3pm-4pm.
If we add the query parameter
limit=100
, then we will create 2 1-hour bars from the first 100 base minute bars that we have stored for that ticker, but we will only return the first 1-hour bar since the second is a partial bar.
Unadjusted
You can pass the
unadjusted
query parameter to any of the agg endpoints to indicate if you want to exclude split adjustments. If
unadjusted=true
then we return the data as collected from our data store. If
unadjusted=false
then we adjust the resulting bars with the splits that occurred within the requested resolution. The default value is
false
, meaning that by default we adjust the results to account for splits.
Example
A request for
AAPL
1-day bars that spans between
2020-08-27
to
2020-08-28
will return 2 results with the opening prices of
127.1425
and
126.0125
respectively.
On the date
2020-08-28
Apple split their stocks 4-for-1. If we make the same request as above, but add the query parameter
unadjusted=true
then we get the opening prices of
508.57
and
504.05
, which is 4x the former opening prices.
Full/Partial Aggregate Bars
By default, the API does not query or return partial aggregate bars. We consider a bar to be full if it includes all of the available base aggregates that fall within the timespan of that bar.
Example
A 1-hour bar made up of aggregates that range from 2pm-3pm is considered full.
A 1-hour bar made up of aggregates that range from 2pm-2:30pm is considered partial.
Corrected Behavior
Limit
Previously it was possible to create partial aggregate bars if the limit prevented the last bar from being completed- now we only return full bars. If the last of the aggregate bars in the result is partial then we omit that bar from the response.
Timespans
A request for Aggregate data spans a time range controlled by the path parameters
multiplier
,
resolution
,
from
and
to
, which all work together to determine the query range to our backing data store. Since we do not return partial aggregate bars by default, we adjust the aggregate query to ensure we return only full bars. We call this process snapping and stretching.
Time Snapping
Snapping a time parameter means changing that time parameter to include a wider range to ensure all the aggregate bars are full. We snap the
from
parameter to the beginning of the
resolution
, and we snap the
to
parameter the end
resolution
.
The following is the beginning and end of each resolution.
| Minute | Hour | Day | Year |
|---|
| Beginning | 2006-01-02T15:04:00.000 | 2006-01-02T15:00:00.000 | 2006-01-02T00:00:00.000 | 2006-01-01T00:00:00.000 |
| End | 2006-01-02T15:04:59.999999999 | 2006-01-02T15:59:59.999999999 | 2006-01-02T23:59:59.999999999 | 2006-12-31T23:59:59.999999999 |
Weeks, Months, and Quarters aren't as easily described via a timestamp, and operate according to this table:
| Week | Month | Quarter |
|---|
| Beginning | Sunday 00:00:00.000 | First Calendar Date of the Month 00:00:00.000 | First Calendar Date of either January, April, July, or October 00:00:00.000 |
| End | Saturday 23:59:59.999999999 | Last Calendar Date of the Month 23:59:59.999999999 | Last Calendar Date of either March, June, September, or December 23:59:99.999999999 |
Time Stretching
Stretching a time parameter means taking into account the
multiplier
parameter to ensure full aggregate bars. Only the
to
time parameter is stretched and that ocurs after it has already been snapped. Stretching the
to
parameters simply means that
to
will move forward in time to the next multiple of
multiplier
and
resolution
.
Examples
A request with a multiplier of
1
and a resolution of
minute
that spans from
2006-01-02T15:04:52.234
to
2006-01-02T15:23:32.12
will result in a query from
2006-01-02T15:04:00.000
to
2006-01-02T15:23:59.999
.
A request with a multiplier of
3
and a resolution of
minute
that spans from
2006-01-02T15:04:52.234
to
2006-01-02T15:23:32.12
will result in a query from
2006-01-02T15:04:00.000
to
2006-01-02T18:24:59.999
.
A request with a multiplier of
1
and a resolution of
hour
that spans from
2006-01-02T15:04:52.234
to
2006-01-02T16:23:32.12
will result in a query from
2006-01-02T15:00:00.000
to
2006-01-02T16:23:59.999
.
A request with a multiplier of
4
and a resolution of
hour
that spans from
2006-01-02T15:04:52.234
to
2006-01-02T17:23:32.12
will result in a query from
2006-01-02T15:0:00.000
to
2006-01-02T19:59:59.999
.
A request with a multiplier of
1
and a resolution of
day
that spans from
2006-01-02T15:04:00.000
to
2006-01-03T15:04:00.000
will result in a query from
2006-01-02T00:00:00.000
to
2006-01-03T23:59:59.999
.
A request with a multiplier of
3
and a resolution of
day
that spans from
2006-01-02T15:04:00.000
to
2006-01-03T15:04:00.000
will result in a query from
2006-01-02T00:00:00.000
to
2006-01-04T23:59:59.999
.
A request with a multiplier of
1
and a resolution of
week
that spans from
Tuesday 15:04:00.000
to
Friday 20:04:00.000
will result in a query from
Sunday 00:00:00.000
to
Saturday 23:59:59.999
.
A request with a multiplier of
2
and a resolution of
week
that spans from
Tuesday 15:04:00.000
to
Friday 20:04:00.000
will result in a query from
Sunday 00:00:00.000
to
Next Saturday 23:59:59.999
.
A request with a multiplier of
1
and a resolution of
month
that spans from
April 1st 15:04:00.000
to
August 7th 20:04:00.000
will result in a query from
April 1st 00:00:00.000
to
August 31st 23:59:59.999
.
A request with a multiplier of
4
and a resolution of
month
that spans from
April 1st 15:04:00.000
to
August 7th 20:04:00.000
will result in a query from
April 1st 00:00:00.000
to
November 30th 23:59:59.999
.
A request with a multiplier of
1
and a resolution of
quarter
that spans from
April 1st 15:04:00.000
to
August 7th 20:04:00.000
will result in a query from
April 1st 00:00:00.000
to
September 30th 23:59:59.999
.
A request with a multiplier of
2
and a resolution of
quarter
that spans from
April 1st 15:04:00.000
to
August 7th 20:04:00.000
will result in a query from
April 1st 00:00:00.000
to
September 30th 23:59:59.999
.
A request with a multiplier of
1
and a resolution of
year
that spans from
April 1st 15:04:00.000
to
August 7th 20:04:00.000
will result in a query from
2006-01-01T00:00:00.000
to
2006-12-31T23:59:59.999
.
A request with a multiplier of
2
and a resolution of
year
that spans from
April 1st 15:04:00.000
to
August 7th 20:04:00.000
will result in a query from
2006-01-01T00:00:00.000
to
2007-12-31T23:59:59.999
.
Pre-Release API
To allow our users to test and integrate with the new API behaviors we have released this version under the version moniker
vX
,
https://api.polygon.io/vX/aggs/ticker/{ticker}/range/{multiplier}/{resolution}/{from}/{to}
. An example of the a request that has changed due to the new behavior is
https://api.polygon.io/vX/aggs/ticker/AAPL/range/10/year/2020-01-01/2020-01-02?sort=asc&limit=50000
. In the older version of the API this request would return an empty result where as the new behavior corrects the timespan request and returns data from
2010-01-01
to
2020-12-31
.
Release Timelines
The new behavior will be released into the existing API for stocks data on Friday, December 4th 2020 at 5pm ET. The pre-release API will last until a week after the crypto and fx release, which is currently TBD.
If you have any questions or problems with the pre-release version of the API please don't hesitate to contact us at support@polygon.io.
