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.massive.com/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.

MinuteDay
Minute, HourDay, 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.

MinuteHourDayYear
Beginning2006-01-02T15:04:00.0002006-01-02T15:00:00.0002006-01-02T00:00:00.0002006-01-01T00:00:00.000
End2006-01-02T15:04:59.9999999992006-01-02T15:59:59.9999999992006-01-02T23:59:59.9999999992006-12-31T23:59:59.999999999

Weeks, Months, and Quarters aren't as easily described via a timestamp, and operate according to this table:

WeekMonthQuarter
BeginningSunday 00:00:00.000First Calendar Date of the Month 00:00:00.000First Calendar Date of either January, April, July, or October 00:00:00.000
EndSaturday 23:59:59.999999999Last Calendar Date of the Month 23:59:59.999999999Last 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.massive.com/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.massive.com/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@massive.com.

From the blog

See what's happening at massive.com

polygon is now massive Feature Image
announcement

Polygon.io is Now Massive

Polygon.io is now Massive.com. The rebrand reflects our focus on scale, reliability, and continued innovation. Your APIs, accounts, and integrations continue to work without interruption.

Justin

editor