---
title: "Get all highlights"
method: GET
path: "/football/highlights"
tags: ["Football.Highlights"]
---

# Get all highlights

`GET /football/highlights`

## Request

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

> Refresh interval: Once a minute

> Note: Certain highlights might be uploaded whilst the game is playing. Full game recaps tend to be uploaded anywhere from 1 to 48 hours after a match is finished.

  Highlights represent the core of our API. They include various different kinds of clips ranging from real time live events such as insane plays, last minute scores to full game recaps, pre/post match interviews. 

Currently we aggregate videos from many different sources. Depending on the source and verification process we divide the clips into two categories:

| Type        | Description |
| ----------- | ----------- |
| VERIFIED    | Videos come from reputable sources that have been thoroughly inspected. In most cases the clips are from official authors who own the copyrights to the video itself. The hosting platform can impose geo restrictions or prevent direct embedding (`highlights/geo-restrictions/{highlightId}` route can be used to check for potential restrictions). Verified highlights are uploaded anywhere from 1 to 48 hours of the match being finished. |
| UNVERIFIED  | Highlights vary and might not have gone through the verification process or are considered user uploaded. Videos include a wide spectrum of topics such as last minute scores, memorable plays, game recaps, etc. Unverified highlights are considered more real time and might be uploaded even when the match is still being played. The lifetime of these clips vary and is dependant on the hosting platform.       |

Each highlight has a `title` which describes what the video is about. Certain entries will have a `description` as well which is used to further describe the associated clip. The `source` field defines where the clip was aggregated from (e.g. would be *youtube*, *twitter*, *reddit*, *espn*, etc.). For certain sources you will see additional information being present in the `channel` field. By utilising this information you can further narrow down which videos you want to showcase. Highlights might also have an `embedUrl` property which is used to directly embed the videos into your website or mobile application.

Below is an example of what you can aim to achieve with our highlights data:

![Highlights example](https://highlightly.net/assets/img/documentation/football/highlights.png)


## Retrieve highlights

Retrieve a list of highlights 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 highlights relevant to your location.

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

> Note: The Basic/Free plan might have certain restrictions in place. More information can be found [here](https://rapidapi.com/highlightly-api-highlightly-api-default/api/football-highlights-api).

## Query parameters

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

## Headers

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

## Response `200`

- FootballHighlightPaginatedResponseDto
  - `data` FootballHighlightResponseDto[], required
    - `id` number, required
    - `type` string, required
    - `imgUrl` string: Preview picture of the highlight.
    - `title` string, required
    - `description` string
    - `url` string, required: Url location of the video highlight.
    - `embedUrl` string: Url of embeddable video highlight.
    - `match` FootballMatchResponseDto, required
      - `id` number, required
      - `round` string, required
      - `date` string, required
      - `country` FootballCountryResponseDto, required
        - `code` string, required: Country code specified by the ISO 3166 standard.
        - `name` string, required
        - `logo` string, required
      - `awayTeam` FootballTeamResponseDto, required
        - `id` number, required
        - `logo` string
        - `name` string, required
      - `homeTeam` FootballTeamResponseDto, required
        - `id` number, required
        - `logo` string
        - `name` string, required
      - `league` FootballMatchLeagueResponseDto, required
        - `id` number, required
        - `season` number, required
        - `name` string, required
        - `logo` string
      - `state` FootballMatchStateResponseDto, required
        - `description` 'To be announced' | 'Not started' | 'First half' | 'Half time' | 'Second half' | 'Extra time' | 'Break time' | 'Penalties' | 'Suspended' | 'Interrupted' | 'Finished' | 'Finished after penalties' | 'Finished after extra time' | 'Postponed' | 'Cancelled' | 'Abandoned' | 'Awarded' | 'In progress' | 'Unknown', required: State of the match.
        - `clock` number: Current minute of the match.
        - `score` FootballMatchScoreResponseDto, required
          - `current` string: Home - Away score up to penalties.
          - `penalties` string: Home - Away team score after the penalties phase.
    - `channel` string: Channel title of a given highlight.
    - `source` string: Aggregation source from social media and other equivalent platforms.
  - `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)