Skip to content

Building your Application#

Once you have reviewed the API's using the Getting Started Guide you'll want to start building your application integration. The following are a few things to think about along with some requirements and recommendations.

General Data Flow#

Your API connection is secured by an API key. This key is secret and must not be shared with external parties or users. To load data and distribute it to your users, you must:

  1. query the Quarter4 API on a server layer,
  2. store the result and then
  3. send information to your users as they request it.
sequenceDiagram participant Q4 as Quarter4 API participant Server as Your Server participant DB as Your Database participant App as Your App loop About every 15 min Server->>+Q4: What are the predictions for today's games? Q4->>+Server: Team A will win game 1, Team B will win game 2. Server->>+DB: Store results end rect rgb(245, 245, 245) Note over DB,App: Your DB/App Interface App->>+DB: What is the prediction for Game 1? DB->>+App: Team A will win game 1. App->>+DB: What is the prediction for Game 2? DB->>+App: Team B will win game 2. end

This will allow you to use the API key for your Quarter4 API queries from your server, while sending the result to your application users without the api key information.

Important

The response may contain reference to the request URL for links to previous and next pages. These links may contain query variables including the API key. It is important that you do not simply forward the response onto your users but instead store and cache the information on your server and incorporate it into your existing application API.

Caching#

The pre-game predictions may be updated roughly once every 15 minutes as changes occur. We recommend you query our api for updates no quicker than every 15 minutes to retrieve the most recent changes.

Pre-game predictions will not change once a game has started so if you have already retrieved predictions, you do not need to update them once the startDate passes.

Caching the responses will also improve the overall experience as you can store common entities such as the team and player, then later you can reference that stored information by uuid when querying for event and prediction details instead of reloading or requesting the team and player details with each request.

Optimize the use of JSON:API#

All Quarter4 API Responses use the JSON:API response format. This format minimizes repetitive data in the request and allows you to provide some control over what data is included or excluded from each request. Here's a simplified example with a few key details:

GET https://api.quarter4.io/basketball/v2/events?startDate[after]=2022-03-18T15:01:22+00:00&order[startDate]=asc&include=winloss&fields[Event]=uuid,startDate,title&count=1&fields[winloss]=uuid,homeWinProbability,awayWinProbability HTTP/1.1
Accept: application/vnd.api+json

Note

The above example URI shows unencoded [ and ] characters simply for readability. In practice, these characters should be percent-encoded, as noted in the base specification. See “Square Brackets in Parameter Names” in the JSON:API documentation.

{
  "meta": {
    "totalItems": 265,
    "itemsPerPage": 1,
    "currentPage": 1
  },
  "data": [
    {
      "id": "\/basketball\/v2\/events\/ae4c3bbd-b357-4b66-904a-5dc25b3d3a96",
      "type": "Event",
      "attributes": {
        "startDate": "2022-03-18T16:15:00+00:00",
        "title": "South Regional - First Round - Game 7",
        "uuid": "ae4c3bbd-b357-4b66-904a-5dc25b3d3a96"
      },
      "relationships": {
        "winloss": {
          "data": {
            "type": "WinLoss",
            "id": "\/basketball\/v2\/win_losses\/ae4c3bbd-b357-4b66-904a-5dc25b3d3a96"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "\/basketball\/v2\/win_losses\/ae4c3bbd-b357-4b66-904a-5dc25b3d3a96",
      "type": "WinLoss",
      "attributes": {
        "uuid": "ae4c3bbd-b357-4b66-904a-5dc25b3d3a96",
        "homeWinProbability": 33,
        "awayWinProbability": 67
      }
    }
  ]
}

The preceding example includes a list of "Event" results and prediction information for the events in the response. A few key parameters to note are:

The count (and page) parameters#

The count in the query parameters limits the number of results per page in the response. The default is 30 results per page. The response's meta data will contain the totalItems to indicate if there are more imtes available beyond the current page. To query a specific page, include the page parameter starting with 1 as the first page. In this case, for the next result you would include &count=1&page=2 for 1 result per page and results for page 2.

The order parameter (sorting)#

The order query parameter orders the result is a specific order using the following syntax ?order[property]=<asc|desc> for example:

&order[startDate]=asc&order[title]=desc

This order the results first by startDate in ascending order then by title in descending order for items with the same start date. Some APIs may have a default order but in most cases some form of ordering will be desired.

The include parameter#

JSON:API returns results in a relational format and allows you to request a compound document including related resources. In this example, the full entity for the winloss relationship:

 "relationships": {
    "winloss": {
        "data": {
        "type": "WinLoss",
        "id": "\/basketball\/v2\/win_losses\/ae4c3bbd-b357-4b66-904a-5dc25b3d3a96"
        }
    }
}

will be included in the response under the included list:

"included": [
    {
        "id": "\/basketball\/v2\/win_losses\/ae4c3bbd-b357-4b66-904a-5dc25b3d3a96",
        "type": "WinLoss",
        "attributes": {
            "uuid": "ae4c3bbd-b357-4b66-904a-5dc25b3d3a96",
            "homeWinProbability": 33,
            "awayWinProbability": 67
        }
    }
]

Your server side application will need to parse the response to locate included items. This format is most useful when requesting longer lists of information where the relationship could be repeated. For example, if you query for a list of events with multiple results and include the homeTeam and awayTeam. On one entry for "Team A" will be in the included list, but multiple events may reference that same team as teh home or away team. This reduces the overall result size and repetition.

Multiple related resources can be requested in a comma-separated list such as include=winloss,homeTeam,awayTeam

Note

Due to the size of data resources, the Quarter4 api limits the api to as single depth. You may include and Event's homeTeam but not the homeTeam.nextEvent. To do deeper, call the team endpoint and cache the result to use as necessary.

The fields parameter#

The JSON:API response also include support for Sparse Fieldsets. This allows you to be more specific with which data you would like to see in the response's attributes for specific resources. By default ALL attributes will be included but in many cases you are likely only looking at a few so you may wish to exclude others to reduce the size of the response.

In the example above, the Event's fields are uuid, startDate and title:

fields[Event]=uuid,startDate,title
"id": "\/basketball\/v2\/events\/ae4c3bbd-b357-4b66-904a-5dc25b3d3a96",
"type": "Event",
"attributes": {
    "startDate": "2022-03-18T16:15:00+00:00",
    "title": "South Regional - First Round - Game 7",
    "uuid": "ae4c3bbd-b357-4b66-904a-5dc25b3d3a96"
},

while the fields from the winloss for the Even't relationship are: uuid, homeWinProbability, awayWinProbability:

fields[winloss]=uuid,homeWinProbability,awayWinProbability
"id": "\/basketball\/v2\/win_losses\/ae4c3bbd-b357-4b66-904a-5dc25b3d3a96",
"type": "WinLoss",
"attributes": {
    "uuid": "ae4c3bbd-b357-4b66-904a-5dc25b3d3a96",
    "homeWinProbability": 33,
    "awayWinProbability": 67
}

Note

the fields are case sensitive. In the above example fields[Event] refers to the type of resouse you are querying (Event) however the fields[winloss] refers to the Event's winloss attribute so the winloss case must match that of the Events's attribute. Using fields[WinLoss] would not filter the Event winloss attribute properly.

Additional parameters#

Date field types#

If the API refers to a date, for example the Event start date, there may be additional options for filtering by date range. All system dates are in UTC and use the following syntax ?property[<after|before|strictly_after|strictly_before>]=value for example:

&startDate[after]=2022-09-06T15:37:02+00:00

This results in items where start date is after 2022-09-06T15:37:02+00:00 UTC.

A full example to query upcoming NFL events after Sept 6th, 2022 UTC would be:

https://api.quarter4.io/american-football/v2/events?startDate[after]=2022-09-06&order[startDate]=asc&league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0&page=1&count=30