---
title: "Get all matches"
method: GET
path: "/nhl/matches"
tags: ["NHL, NCAAH.Matches"]
---

# Get all matches

`GET /nhl/matches`

## Request

- Base URL: `https://sports.highlightly.net`
- URL: `https://sports.highlightly.net/nhl/matches`
- Auth: none declared. Required headers: `x-rapidapi-host`, `x-rapidapi-key`
- TypeScript: <https://skmtc.dev/highlightly/apis/sports-api-highlightly/docs/nhl/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 |
| -----------  | ----------- |
| 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.         |
| 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.            |
| Finished  | Match has been concluded.          |
| Scheduled    |  Match has not been started yet.         |
| End period  |  Break time between periods.         |
| Half time  | Half time pause between second and third quarter.          |
| In progress  | Game is currently in progress.         |
| Unknown  | Unknown match coverage or state.          |

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

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

## Query parameters

- `league` string
- `date` string
- `timezone` string
- `season` number
- `homeTeamId` number
- `awayTeamId` number
- `homeTeamName` string
- `awayTeamName` string
- `homeTeamAbbreviation` string
- `awayTeamAbbreviation` string
- `homeTeamDisplayName` string
- `awayTeamDisplayName` string
- `limit` number
- `offset` number

## Headers

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

## Response `200`

- NhlMatchPaginatedResponseDto
  - `data` NhlMatchResponseDto[], required
    - `id` number, required
    - `round` string, required
    - `date` string, required
    - `league` string, required
    - `season` number, required
    - `awayTeam` NhlMatchTeamResponseDto, required
      - `id` number, required
      - `logo` string
      - `name` string
      - `displayName` string, required
      - `abbreviation` string, required
    - `homeTeam` NhlMatchTeamResponseDto, required
      - `id` number, required
      - `logo` string
      - `name` string
      - `displayName` string, required
      - `abbreviation` string, required
    - `state` NhlMatchStateResponseDto, required
      - `period` number: Current in play period.
      - `clock` number: Current minute of the in play period.
      - `description` 'Suspended' | 'Postponed' | 'Cancelled' | 'Abandoned' | 'Finished' | 'In progress' | 'End period' | 'Half time' | 'Unknown' | 'Scheduled', required: Current status/description of the match.
      - `score` NhlMatchScoreResponseDto, required
        - `current` string: Home - Away score for the match.
        - `firstPeriod` string: Home - Away score in 1st period.
        - `secondPeriod` string: Home - Away score in 2nd period.
        - `thirdPeriod` string: Home - Away score in 3rd period.
        - `overtimePeriod` string: Home - Away score in the overtime period.
      - `report` string: Additional description of the match state.
  - `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)