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.
