---
title: "Get all matches"
method: GET
path: "/hockey/matches"
tags: ["Hockey.Matches"]
---

# Get all matches

`GET /hockey/matches`

## Request

- Base URL: `https://sports.highlightly.net`
- URL: `https://sports.highlightly.net/hockey/matches`
- Auth: none declared. Required headers: `x-rapidapi-host`, `x-rapidapi-key`
- TypeScript: <https://skmtc.dev/highlightly/apis/sports-api-highlightly/docs/hockey/matches/get.ts> (a function with typed inputs; its response is checked against the schema)

> Refresh interval: Once a minute

> Route returns only general match information. For additional match details check the `matches/{matchId}` route. 

Retrieve a list of matches based on the requested query parameters. 

At least one primary query parameter needs to be specified before you can retrieve the data (`timezone`, `limit`, `offset` are considered secondary).

You can specify the `timezone` field in combination with the `date` query parameter to get matches relevant to your location.

There are two other important parameters. The `limit` parameter defines what the number of returned matches will be. If the number of actual matches is above the `limit` value you can make subsequent requests by increasing the `offset` value. 

Matches have different possible states they can be in:

| State        | Description |
| -----------  | ----------- |
| Not started    |  Match has not been started yet.         |
| 1st period  |  Match is in the first period of regular play.         |
| 2nd period | Match is in the second period of regular play.        |
| 3nd period | Match is in the third period of regular play.          |
| Over time  | Game was considered a draw in normal time. Additional extra time is needed to decide the winner.          |
| Break time  | Short pause between in play periods and over time.       |
| Penalties  | Penalty shootout to decide the winner of the match.         |
| Finished  | Match has been concluded.          |
| Finished after penalties  | Match has been concluded with the penalty shootout.         |
| Finished after over time  | Match has been concluded in over time.         |
| Postponed  | Match has been postponed due to certain circumstances that are preventing the game from being played. Event start time will be changed to a moment in the future.           |
| Suspended  |  Match has already been in play but was suspended. In the future the game will resume from the exact point where it was halted.         |
| Cancelled  |  Game will not be played.         |
| Awarded  |  Game awarded to one of the teams when the other forfeits or specific circumstances have been met such as insufficient players, late arrival, team withdrawl, etc.          |
| Interrupted  | An issue arose that is preventing the game from continuing. Based on the interruption the game will either resume normal play or be abandoned.          |
| Abandoned  | Considered "abandoned" when it is prematurely ended by the officials and can not be resumed or completed. In the future the game **might be** resumed from the exact point where it was halted.            |
| Unknown  | Unknown match coverage or state.          |
| To be announced  | Match's start time will be updated or competing teams are not yet known.          |

Below is an example of what you can aim to achieve with the matches endpoint:

![Hockey matches example](https://highlightly.net/assets/img/documentation/hockey/matches.png)

## Query parameters

- `leagueName` string
- `leagueId` number
- `date` string
- `timezone` string
- `season` number
- `homeTeamId` number
- `awayTeamId` number
- `homeTeamName` string
- `awayTeamName` string
- `countryCode` string
- `countryName` string
- `limit` number
- `offset` number

## Headers

- `x-rapidapi-host` string, required
- `x-rapidapi-key` string, required

## Response `200`

- HockeyMatchPaginatedResponseDto
  - `data` HockeyMatchResponseDto[], required
    - `id` number, required
    - `week` string
    - `date` string, required
    - `country` HockeyCountryResponseDto, required
      - `code` string, required: Country code specified by the ISO 3166 standard.
      - `name` string, required
      - `logo` string, required
    - `awayTeam` HockeyTeamResponseDto, required
      - `id` number, required
      - `logo` string
      - `name` string, required
    - `homeTeam` HockeyTeamResponseDto, required
      - `id` number, required
      - `logo` string
      - `name` string, required
    - `league` HockeyMatchLeagueResponseDto, required
      - `id` number, required
      - `season` number, required
      - `name` string, required
      - `logo` string
    - `state` HockeyMatchStateResponseDto, required
      - `description` 'Not started' | '1st period' | '2nd period' | '3rd period' | 'Over time' | 'Penalties' | 'Break time' | 'Awarded' | 'Postponed' | 'Cancelled' | 'Interrupted' | 'Abandoned' | 'Finished' | 'To be announced' | 'Finished after penalties' | 'Finished after over time' | 'Unknown', required: Current state of the game.
      - `score` HockeyMatchScoreResponseDto, required
        - `current` string: Home - Away score for the match.
        - `overTime` string: Home - Away score in overtime.
        - `penalties` string: Home - Away score in penalties.
        - `firstPeriod` string: Home - Away score in 1st period.
        - `secondPeriod` string: Home - Away score in 2nd period.
        - `thirdPeriod` string: Home - Away score in 3rd period.
  - `pagination` PaginationResponseDto, required
    - `totalCount` number, required: Available number of items, relevant to the provided query.
    - `offset` number, required
    - `limit` number, required
  - `plan` PlanResponseDto, required
    - `tier` string, required: Your current API subscription tier.
    - `message` string, required: Explanation message regarding your current tier.

## Other responses

- `400`: Bad request descriptive error.
- `500`: Internal server error.

---

[API](https://skmtc.dev/highlightly/apis/sports-api-highlightly.md) - [All operations](https://skmtc.dev/highlightly/apis/sports-api-highlightly/llms.txt) - [OpenAPI document](https://skmtc.dev/highlightly/apis/sports-api-highlightly/revisions/c8a366d3091f?raw)