Sports Data Entity Hierarchy APIs#

The following describes how to retrieve the general hierarchy of entities used across the Sports Data APIs.

Using the REST API to Query for Entity Hierarchies#

Related Sports Data APIS

Method	Description	Availability
`GET`	`/{sport}/v2/leagues`	All Leagues
`GET`	`/{sport}/v2/conferences`	All Leagues
`GET`	`/{sport}/v2/divisions`	All Leagues
`GET`	`/{sport}/v2/teams`	All Leagues
`GET`	`/{sport}/v2/players`	All Leagues

You can retrieve the hierarchy of entities using the league, conference, division, team, and player endpoints. Typically a sport will follow that order:

classDiagram League -- Conference Conference -- Division Division -- Team Team -- Player League: +conferences Conference: +League league Conference: +Division[] divisions Division: +Conference conference Division: +Teams[] teams Team: +Conference conference Team: +Division division Team: +Player[] currentPlayers Player: +Team team

In the case of some leagues such as NCAA leagues, the conference and division may be swapped:

classDiagram League -- Division Division -- Conference Conference -- Team Team -- Player League: +Divisions Division: +League league Division: +Conference[] Conferences Conference: +Division Division Conference: +Teams[] teams Team: +Division Division Team: +Conference Conference Team: +Player[] currentPlayers Player: +Team team

In order to correctly query the hierarchy you will need to know which league you would like and how it is generally structured.

For example, to load the NBA basketball hierarchy you can start with the leagues query:

GET https://api.quarter4.io/basketball/v2/leagues

which will return a list of all the available leagues (here only NBA):

{
  "links": {
    "self": "\/basketball\/v2\/leagues"
  },
  "meta": {
    "totalItems": 1,
    "itemsPerPage": 30,
    "currentPage": 1
  },
  "data": [
    {
      "id": "\/basketball\/v2\/leagues\/634e7f95-8209-4846-beb5-cf8555f99237",
      "type": "League",
      "attributes": {
        "name": "NBA",
        "abbreviation": "NBA",
        "displayName": "NBA",
        "seasonStartDate": "2021-10-03T19:30:00+00:00",
        "seasonEndDate": "2022-06-17T05:19:07+00:00",
        "uuid": "634e7f95-8209-4846-beb5-cf8555f99237"
      },
      "relationships": {
        "conferences": {
          "data": [
            {
              "type": "Conference",
              "id": "\/basketball\/v2\/conferences\/7a409bed-a3bd-460c-891b-dce72dcf233e"
            },
            {
              "type": "Conference",
              "id": "\/basketball\/v2\/conferences\/04be996a-2a9d-4f39-bf20-f9e5d5f4d7b4"
            }
          ]
        },
        "season": {
          "data": {
            "type": "Season",
            "id": "\/basketball\/v2\/seasons\/7f0c8940-26c2-11ec-b9cb-02f89bed6fe2"
          }
        }
      }
    }
  ]
}

If you already know the UUID of the league, you can also query it directly using the uuid as part of the leagues query:

GET https://api.quarter4.io/basketball/v2/leagues/634e7f95-8209-4846-beb5-cf8555f99237

which will return just the one league:

{
  "data": {
    "id": "\/basketball\/v2\/leagues\/634e7f95-8209-4846-beb5-cf8555f99237",
    "type": "League",
    "attributes": {
      "name": "NBA",
      "abbreviation": "NBA",
      "displayName": "NBA",
      "seasonStartDate": "2021-10-03T19:30:00+00:00",
      "seasonEndDate": "2022-06-17T05:19:07+00:00",
      "uuid": "634e7f95-8209-4846-beb5-cf8555f99237"
    },
    "relationships": {
      "conferences": {
        "data": [
          {
            "type": "Conference",
            "id": "\/basketball\/v2\/conferences\/7a409bed-a3bd-460c-891b-dce72dcf233e"
          },
          {
            "type": "Conference",
            "id": "\/basketball\/v2\/conferences\/04be996a-2a9d-4f39-bf20-f9e5d5f4d7b4"
          }
        ]
      },
      "season": {
        "data": {
          "type": "Season",
          "id": "\/basketball\/v2\/seasons\/7f0c8940-26c2-11ec-b9cb-02f89bed6fe2"
        }
      }
    }
  }
}

Now you have the League entity attributes:

"attributes": {
    "name": "NBA",
    "abbreviation": "NBA",
    "displayName": "NBA",
    "seasonStartDate": "2021-10-03T19:30:00+00:00",
    "seasonEndDate": "2022-06-17T05:19:07+00:00",
    "uuid": "634e7f95-8209-4846-beb5-cf8555f99237"
},

as well as the League entity relationships:

"relationships": {
    "conferences": {
        "data": [
            {
                "type": "Conference",
                "id": "\/basketball\/v2\/conferences\/7a409bed-a3bd-460c-891b-dce72dcf233e"
            },
            {
                "type": "Conference",
                "id": "\/basketball\/v2\/conferences\/04be996a-2a9d-4f39-bf20-f9e5d5f4d7b4"
            }
        ]
    },
    "season": {
        "data": {
            "type": "Season",
            "id": "\/basketball\/v2\/seasons\/7f0c8940-26c2-11ec-b9cb-02f89bed6fe2"
        }
    }
}

Next, to load the conferences there are a three ways you can do that.

First, you can use the data.relationships.conferences.data[].id to formulate the single conference query:

GET https://api.quarter4.io/basketball/v2/conferences/7a409bed-a3bd-460c-891b-dce72dcf233e

Second, you can ask for all conferences:

GET https://api.quarter4.io/basketball/v2/conferences

then match each of the conference JSON:API ids in the result to the JSON:API ids in the initial data.relationships.conferences.data[] to match them up.

Third, you can alter your original query and use include=conferences to include the child conference information in the original result:

GET https://api.quarter4.io/basketball/v2/leagues/634e7f95-8209-4846-beb5-cf8555f99237?include=conferences

This will return a similar result (below) with an additional data.included array containing all the included Conference entities and the Confrence entity attributes. You still need to loop through the data.included array matching the JSON:API ids to the JSON:API ids in the data.relationships.conferences.data[] relationships but all required entities are returned in one query.

Using include

The include parameter includes the child entity's attributes and relationships but not the full attributes on the relationships. Include only works for one level of nesting. For example, you can not use include=conferences.divisions in this same query so you will need to decide how to best optimize your queries to retrieve the information you need.

{
  "data": {
    "id": "\/basketball\/v2\/leagues\/634e7f95-8209-4846-beb5-cf8555f99237",
    "type": "League",
    "attributes": {
      "name": "NBA",
      "abbreviation": "NBA",
      "displayName": "NBA",
      "seasonStartDate": "2021-10-03T19:30:00+00:00",
      "seasonEndDate": "2022-06-17T05:19:07+00:00",
      "uuid": "634e7f95-8209-4846-beb5-cf8555f99237"
    },
    "relationships": {
      "conferences": {
        "data": [
          {
            "type": "Conference",
            "id": "\/basketball\/v2\/conferences\/7a409bed-a3bd-460c-891b-dce72dcf233e"
          },
          {
            "type": "Conference",
            "id": "\/basketball\/v2\/conferences\/04be996a-2a9d-4f39-bf20-f9e5d5f4d7b4"
          }
        ]
      },
      "season": {
        "data": {
          "type": "Season",
          "id": "\/basketball\/v2\/seasons\/7f0c8940-26c2-11ec-b9cb-02f89bed6fe2"
        }
      }
    }
  },
  "included": [
    {
      "id": "\/basketball\/v2\/conferences\/7a409bed-a3bd-460c-891b-dce72dcf233e",
      "type": "Conference",
      "attributes": {
        "name": "EASTERN CONFERENCE",
        "abbreviation": "EASTERN",
        "uuid": "7a409bed-a3bd-460c-891b-dce72dcf233e"
      },
      "relationships": {
        "divisions": {
          "data": [
            {
              "type": "Division",
              "id": "\/basketball\/v2\/divisions\/b72d188c-1581-41ce-9ba9-a3e5dcc6b9ac"
            },
            {
              "type": "Division",
              "id": "\/basketball\/v2\/divisions\/f3b9cfc5-44a3-456b-b550-2311354db47f"
            },
            {
              "type": "Division",
              "id": "\/basketball\/v2\/divisions\/ea6c5aa7-f6ed-499b-9231-c95ff8c3b934"
            }
          ]
        },
        "teams": {
          "data": [
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/6d5d29a1-12cb-4f76-baab-4c347b98b113"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/a791be09-ced3-407f-a4de-11bce1f4ddf1"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/6dcc4934-a78c-4514-a435-e0653315fbc3"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/05c5fe22-3363-424c-b8a7-f924491940b7"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/974d3b03-6509-40a7-a479-7326d8741a16"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/42535925-5352-4927-84db-0be4f3af823a"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/bb980b2c-88df-442b-b2d2-97e73c301c1f"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/111250b9-fb42-4b6d-8e8e-72f5a4971ed7"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/ea3c270c-15a7-48d7-8668-1ae57003fb2c"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/6697d05c-db4f-4d36-b85f-0f58e39d9e7e"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/cb10d31a-f472-4fa5-8da2-d994bba9eb0b"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/6c5b89b9-912e-4df5-bfe5-290cb1a7edcb"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/bb425691-8689-4adc-a9ef-323dc6d8c6c1"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/d4c5d92a-43dd-40f9-96cc-c23f68733736"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/383c4212-7c01-4721-a0a8-3a7e81d216c6"
            }
          ]
        }
      }
    },
    {
      "id": "\/basketball\/v2\/conferences\/04be996a-2a9d-4f39-bf20-f9e5d5f4d7b4",
      "type": "Conference",
      "attributes": {
        "name": "WESTERN CONFERENCE",
        "abbreviation": "WESTERN",
        "uuid": "04be996a-2a9d-4f39-bf20-f9e5d5f4d7b4"
      },
      "relationships": {
        "divisions": {
          "data": [
            {
              "type": "Division",
              "id": "\/basketball\/v2\/divisions\/b21bccdb-2125-46d3-853d-1ce1953c5bc6"
            },
            {
              "type": "Division",
              "id": "\/basketball\/v2\/divisions\/068565d7-9516-4d35-b76f-9a1856702262"
            },
            {
              "type": "Division",
              "id": "\/basketball\/v2\/divisions\/51b879eb-375c-4709-ae41-988f2bb8be56"
            }
          ]
        },
        "teams": {
          "data": [
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/5aefb945-851b-4d45-b837-d62954151411"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/4e252a5d-2af7-4794-b6ee-46272d98706a"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/15638a0a-1a2e-4936-aa6b-4424aff1f49e"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/3ec16100-793a-44e3-a537-b6748fc1b0b6"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/6ff0217b-a40f-441b-b72f-c64cf3188438"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/ef55c3ac-f782-4b39-ab21-9c22e1a5571c"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/91a04f13-d8af-4979-b912-ce4a50cf579b"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/3074b461-8625-432f-b065-fc64f5091bd2"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/b631808c-02c8-4d45-9507-37f328b8f7f0"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/09195e1a-d612-4920-a975-d2f1ed776950"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/0852ba62-1d42-4586-9a45-b9246d525bfe"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/e293ad76-3296-4429-adac-528f4ff463f4"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/74176315-02a6-4fa9-916c-ba6461ec39a4"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/9b8b4dc9-9c56-4228-b4b2-8cfe532456cf"
            },
            {
              "type": "Team",
              "id": "\/basketball\/v2\/teams\/6ba90c1c-a5ed-4ef4-bb93-d29eb8ad96ec"
            }
          ]
        }
      }
    }
  ]
}

and so on...

Given the example above, the same applies for all levels of the hierarchy. For example:

Load all Division entities:

GET https://api.quarter4.io/basketball/v2/divisions

or Team entities:

GET https://api.quarter4.io/basketball/v2/teams

Load a single team and all the teams currentPlayers with:

GET https://api.quarter4.io/basketball/v2/teams/6d5d29a1-12cb-4f76-baab-4c347b98b113?include=currentPlayers

Check out the interactive Sports Data API documentation to explore the various attributes and relationships on each entity type.

Checking for Changes

The league, division and conference Entities rarely change. You can cache these entities in your local Database and rely on them regularity. Other entities such as Team may change daily while events and predictions can change up to every 15 minutes. See Checking for Changes in the interactive documentation for more detail on how to monitor changes.

Searching for Entities by Name#

Many entities support name searches along with the API queries. For example, to search for all players with the firstName "Jeff" in the NFL you can use firstName=Jeff:

GET https://api.quarter4.io/american-football/v2/players?firstName=Jeff&league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0

Name word based searches are partial matches so be sure to verify your results to ensure you are referencing the correct person. You May want to include additional query parameters such as lastName, uniform, team.uuid, etc. to narrow results. Refer to the interactive API docs to see which properties are available for query searches.