Update Frequencies
Intro
Each NHL API endpoint updates at a variable frequency, in terms of both its cache and its data.
For example, a Game endpoint may have a 2 second cache during a live game and a 120 second cache outside of a live game. Alternatively, a Standings endpoint may have a 120 second cache, but the data within will only update when games conclude. And during the offseason data will not update at all.
Given your limited amount of API requests and QPS, these frequencies should be understood and factored into your pull rate.
Use this section to help determine the best pull frequency for your needs.
Time-to-Live (TTL) and Data Updates
Understanding the distinction between TTL and data updates is crucial for designing an efficient and reliable NHL API solution. TTL is focused on the validity of cached data to optimize performance, whereas data updates are concerned with the actual data within the API.
Time-to-Live (TTL)
Time-to-Live (TTL) is a mechanism used to define the lifespan of data in a cache or network. It specifies the duration for which the data remains valid and can be reused. Once the TTL expires, the data could be stale and must be re-fetched.
You can find the TTL for each RESTful feed in the response header of a request under Cache-Control. A response of public, must-revalidate, max-age=300 signifies a time-to-live of 300 seconds.
Data Updates
Data Updates refer to the changes made to the underlying data that the API provides access to. This can occur through various operations such as creating, updating, or deleting our sports data.
Data updates are critical to ensuring that the API delivers the most current and accurate information. Data entry workflows and processes specific to NHL data will affect your suggested request frequency.
See a daily breakdown of data updates for the NHL API.
Additional Frequency Resources
NHL API responses also provide expires and etag headers. Toggle between the two header samples below to get an idea of how each functions.
Expires
Use the expires header date to determine a specific time to re-fetch data. In cases, it may be more convenient than computing the date of the content alongside the TTL.
Etags
Use the etags header to check if the content has changed between requests.
< HTTP/2 200
< content-type: application/xml;charset=utf-8
< content-length: 884005
< date: Wed, 03 Jul 2024 18:21:13 GMT
< x-amzn-requestid: 87355d21-5a20-429a-95e9-b36d406a992f
< strict-transport-security: max-age=15724800; includeSubDomains
< x-amzn-remapped-content-length: 884005
< content-language: en
< x-amzn-remapped-connection: close
< x-amz-apigw-id: aWR3wGSRIAMEddQ=
< cache-control: public, must-revalidate, max-age=120
< expires: Wed, 03 Jul 2024 18:23:12 GMT
< etag: "2b358d2fe60303e7bbd1be3d64a37cfe"
< x-via: Delivery-Proxy
< x-amzn-trace-id: Root=1-66859697-752ac4fa2c40a4586900aa76;Parent=667fb8ce9acca5af;Sampled=0;lineage=b9fe645c:0
< x-amzn-remapped-date: Wed, 03 Jul 2024 18:21:13 GMT
< via: 1.1 72b77c557ac4c265c32d99bdef4e9d6a.cloudfront.net (CloudFront), 1.1 d1b7c750b45b2751c2c1a34c2f5af9ec.cloudfront.net (CloudFront)
< x-amz-cf-pop: IAD79-C3
< vary: Accept-Encoding
< x-cache: Hit from cloudfront
< x-amz-cf-pop: ORD58-P6
< x-amz-cf-id: -u_iAJXYbBsYDq3ex20s2Sj7z0m-yIx5CDRpGHIPxz4k58-Pl-857A==
< age: 13< HTTP/2 200
< content-type: application/xml;charset=utf-8
< content-length: 884005
< date: Wed, 03 Jul 2024 18:32:17 GMT
< x-amzn-requestid: 0211fcbe-b272-49fc-9c2e-bc8c8fded090
< strict-transport-security: max-age=15724800; includeSubDomains
< x-amzn-remapped-content-length: 884005
< content-language: en
< x-amzn-remapped-connection: close
< x-amz-apigw-id: aWTfeFFkIAMEvvA=
< cache-control: public, must-revalidate, max-age=120
< expires: Wed, 03 Jul 2024 18:34:16 GMT
< etag: "94bf0a9737dd296c3ebf95f0b9de9ea5"
< x-via: Delivery-Proxy
< x-amzn-trace-id: Root=1-6685992f-41c8513b6c9423d36b717894;Parent=7c945e91890c1d79;Sampled=0;lineage=b9fe645c:0
< x-amzn-remapped-date: Wed, 03 Jul 2024 18:32:17 GMT
< via: 1.1 c3fbf93d9b0f1f9b36fcc420314f3186.cloudfront.net (CloudFront), 1.1 049d2c2e11b2a18bd6ce7ab8a5981ed2.cloudfront.net (CloudFront)
< x-amz-cf-pop: IAD79-C3
< vary: Accept-Encoding
< x-cache: Miss from cloudfront
< x-amz-cf-pop: ORD58-P6
< x-amz-cf-id: wjObvD9E5r97H03nJ95mPb1bmnnTOaLoLMtX9kOptCpyLqBQvz3Wpg==Frequency Chart
What is the right request frequency for your use? Which endpoints should you pull to get the most efficient use of your allotted calls?
The below chart provides answers to these questions, with a breakdown of the cache and data updates for every NHL API endpoint, as well as our recommended pulling frequency.
Endpoint | TTL / Cache | Data Updates | Recommended Pull (Non-Live) | Recommended Pull (Live) |
|---|---|---|---|---|
300 Seconds | As necessary | Pull on an as needed basis | Not applicable | |
300 Seconds | Entries populate live for changes to teams, players, game statistics, schedules, and standings Start time of the log is 05:00:00 UTC; end time is 04:59:59 UTC | Pull every ten minutes or less, depending on your use case | Not applicable | |
10 seconds | Schedule info is updated in realtime as changes are made | Pull every hour or less, depending on your use case Note that this feed should be used for schedule info prior to a game start For status of a live game, reference a "game" endpoint | Not applicable Use this feed for non-live schedule retrieval only | |
300 seconds | Updates are made in realtime as transactions are entered | Pull every hour or less, depending on your use case | Not applicable | |
300 seconds | Depth Chart info is updated in realtime as changes are made known | Pull every hour or less, depending on your use case | Not applicable | |
300 seconds | Updates are made in realtime as changes are made to rosters or player profiles | Pull every hour or less, depending on your use case | Not applicable | |
This endpoint will update to a 2s TTL (time to live) upon a game moving to inprogress Upon closed, it will transfer to 120s | Realtime | Pull on an as-needed basis Feed can be ignored until 30 minutes before the scheduled game start, depending on your use case Utilize the daily change log to capture data changes after a game has ended | Can request as fast as every 2 seconds (matching the TTL) when a game is live Game feeds should be requested 10 minutes before the scheduled start | |
This endpoint will update to a 2s TTL (time to live) upon a game moving to inprogress Upon closed, it will transfer to 120s | Realtime | Pull on an as-needed basis Feed can be ignored until 10 minutes before the scheduled game start, depending on your use case Utilize the daily change log to capture data changes after a game has ended | Can request as fast as every 2 seconds (matching the TTL) when a game is live Game feeds should be requested 10 minutes before the scheduled start | |
This endpoint will update to a 2s TTL (time to live) upon a game moving to inprogress. Upon closed, it will transfer to 120s | Realtime | Pull on an as-needed basis Feed can be ignored until 10 minutes before the scheduled game start, depending on your use case Utilize the daily change log to capture data changes after a game has ended | Can request as fast as every 2 seconds (matching the TTL) when a game is live Game feeds should be requested 10 minutes before the scheduled start | |
This endpoint will update to a 2s TTL (time to live) upon a game moving to inprogress Upon closed, it will transfer to 120s | Realtime | Pull on an as-needed basis Feed can be ignored until 10 minutes before the scheduled game start, depending on your use case Utilize the daily change log to capture data changes after a game has ended | Can request as fast as every 2 seconds (matching the TTL) when a game is live Game feeds should be requested 10 minutes before the scheduled start | |
This endpoint will update to a 2s TTL (time to live) upon a game moving to inprogress Upon closed, it will transfer to 120s | Realtime | Pull on an as-needed basis Feed can be ignored until 10 minutes before the scheduled game start, depending on your use case Utilize the daily change log to capture data changes after a game has ended | Can request as fast as every 2 seconds (matching the TTL) when a game is live Game feeds should be requested 10 minutes before the scheduled start | |
This endpoint will update to a 2s TTL (time to live) upon a game moving to inprogress Upon closed, it will transfer to 120s | Realtime | Pull on an as-needed basis Feed can be ignored until 30 minutes before the scheduled game start, depending on your use case Utilize the daily change log to capture data changes after a game has ended | Can request as fast as every 2 seconds (matching the TTL) when a game is live Game feeds should be requested 10 minutes before the scheduled start | |
This endpoint will update to a 2s TTL (time to live) upon a game moving to inprogress Upon closed, it will transfer to 120s | Realtime | Pull on an as-needed basis Feed can be ignored until 10 minutes before the scheduled game start, depending on your use case Utilize the daily change log to capture data changes after a game has ended | Can request as fast as every 2 seconds (matching the TTL) when a game is live Game feeds should be requested 10 minutes before the scheduled start | |
300 seconds | Injuries are made available depending on the day of the game See our Data Entry Workflow section for specific timings on "injury updates" | Pull every hour or less, depending on your use case | Not applicable | |
300 seconds | Hierarchy updates will appear as they are updated in the database | Pull daily or less, depending on your use case | Not applicable | |
120 seconds | League Leaders are updated nightly after all games are closed and statistics validated | Pull daily or less, depending on your use case | Not applicable | |
120 seconds | League Leaders are updated nightly after all games are closed and statistics validated | Pull daily or less, depending on your use case | Not applicable | |
120 seconds | League Leaders are updated nightly after all games are closed and statistics validated | Pull daily or less, depending on your use case | Not applicable | |
120 seconds | League Leaders are updated nightly after all games are closed and statistics validated | Pull daily or less, depending on your use case | Not applicable | |
120 seconds | Stats are updated around 5 minutes after a game is moved to closed | Pull on an as-needed basis Utilize the daily change log to capture data changes after a game has ended | Pull 5-10 mins after a game is moved to closed to receive the quickest updates | |
120 seconds | Rankings are updated nightly, 60 minutes after all games are over | Pull every hour or less, depending on your use case | Not applicable | |
10 seconds | Schedule information is updated in realtime as changes are made | Pull every hour or less, depending on your use case Note that this feed should be used for schedule info prior to a game start For status of a live game, reference a "game" endpoint | Not applicable Use this feed for non-live schedule retrieval only | |
120 seconds | Seasonal stats are updated around 5 minutes after a game is moved to closed | Pull on an as-needed basis Utilize the daily change log to capture data changes after a game has ended | Pull 5-10 mins after a game is moved to closed to receive the quickest updates | |
120 seconds | Award entries are added as they are announced | Pull on an as-needed basis | Pull 5-10 mins after a game is moved to closed to receive the quickest updates | |
120 seconds | Seasonal stats are updated around 5 minutes after a game is moved to closed | Pull on an as-needed basis | Pull 5-10 mins after a game is moved to closed to receive the quickest updates | |
120 seconds | Seasonal stats are updated around 5 minutes after a game is moved to closed | Pull on an as-needed basis | Pull 5-10 mins after a game is moved to closed to receive the quickest updates | |
120 seconds | Seasonal stats are updated around 5 minutes after a game is moved to closed | Pull on an as-needed basis | Pull 5-10 mins after a game is moved to closed to receive the quickest updates | |
300 seconds | New seasons will appear as they are added to the database The season status is updated on the same day | Pull on an as-needed basis | Not applicable | |
120 seconds | Series stats are updated around 5 minutes after a game is moved to closed | Pull on an as-needed basis | Pull 5-10 mins after a series game is moved to closed to receive the quickest updates | |
2 seconds | Schedule info is updated in realtime as changes are made The initial playoff schedule (with TBD matchups) will be available shortly after the regular season schedule is released | Pull on an as-needed basis | Pull 5-10 mins after a series game is moved to closed to receive the quickest updates | |
120 seconds | Series stats are updated around 5 minutes after a game is moved to closed | Pull on an as-needed basis | Pull 5-10 mins after a series game is moved to closed to receive the quickest updates | |
120 seconds | Standings are updated within 5 minutes of each game moving to complete | Pull on an as-needed basis | Pull 5-10 mins after a game is moved to closed to receive the quickest updates | |
120 seconds | Team Leaders are updated nightly after all games are closed and statistics validated | Pull daily or less, depending on your use case | Not applicable | |
120 seconds | Team Leaders are updated nightly after all games are closed and statistics validated | Pull daily or less depending on your use case | Not applicable | |
300 seconds | Updates are made in realtime as changes are made to rosters or player profiles | Pull every hour or less, depending on your use case | Not applicable | |
300 seconds | New teams will appear as they are added to the database | Pull on an as-needed basis | Not applicable |
Important NotePull recommendations are based on a typical customer's needs. We suggest starting with our recommended rate and adjusting as necessary according to your needs.
Updated about 1 hour ago