Highlightly Handball API (5.2.1)

Refresh interval: Once a day

Retrieve a list of countries that are supported by the API.

By utilising the name query parameter you can check whether a specific country exists or simply retrieve the associated data.

Country name and code can be used to query other resources such as matches, leagues, highlights, etc.

Below is an example of supported countries and their associated logos:

Refresh interval: Once a day

Retrieve associated country details by specifying the country code path parameter. The path parameter should follow the ISO 3166 standard.

Country name and code can be used to query other resources such as matches, leagues, highlights, etc.

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:

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:

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.

Refresh interval: Once an hour

Note: Endpoint is not available in the Basic/Free plan.

Geo restrictions are a plague that have been around for quite a while. They restrict access to online content based on the viewers geographical location. Trying to show restricted highlights to your users can greatly hinder the viewing experience.

Each highlight has a state property which defines how the geo restrictions are applied.

As presented before, certain highlights have an embedUrl field which can be used to directly embed the video into your website or application. The embeddable field specifies whether this is allowed or not.

Retrieve highlight information by specifying the highlight id path parameter.

Note: Used to check whether a highlight still exists or had its information updated.

Refresh interval: Multiple times a day

Retrieve a list of leagues.

By utilising the leagueName query parameter you can check whether a specific league exists or simply retrieve the associated data. You can also narrow down your search by specifying the countryCode or countryName query parameters.

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

The league information and their associated seasons can be used to request data from other endpoints such as standings.

Retrieve league information by specifying the league id path parameter.

Note: Used to check whether a league still exists or had its information updated.

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:

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

Retrieve detailed match information by specifying the match id path parameter.

Certain popular leagues and their associated matches will have additional data about the venue and match weather forecast.

Note: Used to retrieve additional match information.

Retrieve a list of teams that are supported by the API.

By utilising the name query parameter you can check whether a specific team exists or simply retrieve the associated data.

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

Refresh interval: Immediately once a match is finished.

Retrieve team stats for each league and season by specifying the team's id path parameter. Requires fromDate query parameter to be specified in the YYYY-MM-DD format. Additionally, the timezone query parameter can be specified to futher narrow down the search results based on your location.

Retrieve team information by specifying the team id path parameter.

Note: Used to check whether a team still exists or had its information updated.

Refresh interval: Once a day

Retrieve a list of supported bookmakers.

There are two important parameters that are used to navigate through the pagination. The limit parameter defines what the number of returned bookmakers will be. If the number of actual bookmakers is above the limit value you can make subsequent requests by increasing the offset value.

The bookmakers name or id can be used to filter data from the odds endpoint.

Retrieve bookmaker information by specifying the bookmaker id path parameter.

Note: Used to check whether a bookmaker still exists or had its information updated.

Prematch odds refresh interval: Multiple times a day

Live odds refresh interval: Once every 10 minutes

Note: Endpoint is not available in the Basic/Free plan.

Retrieve a list of match odds based on the requested query parameters. With oddsType query parameter you can specify whether you want prematch or live odds. If you do not set a specific value prematch odds will be returned.

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

The most popular way of getting match odds is by specifying the matchId query parameter. You can also utilise the date parameter alongside the timezone to fetch all match odds for a given day. By specifying league or bookmaker related fields you can further narrow down your search.

As it stands, we currently offer the support for the following markets:

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

Match odds are available up to 28 days after the game finishes and up to 7 days before the game starts.

Below is an example of what can be achieved with bookmaker odds on a match basis:

Refresh interval: Immediately once a game is considered finished

Retrieve a list of the last five finished games for a specific team. If a game was not finished (e.g. was cancelled or postponed) it will not be returned.

Specify teamId query parameter to retrieve the data. Endpoint is used to create a form section between two teams that are playing a match. Below is an example of what can be achieved:

Retrieve a list of the last ten head 2 head games between two teams. Compare the two teams to find out who is stronger based on their past match results.

Specify teamIdOne and teamIdTwo query parameters to retrieve the data. The order of team ids does not matter.

Below is an example of what you can achieve with the data:

Refresh interval: Up to an hour after a match for the associated league and season is finished

Retrieve standings data for a specific league, conference or division.

Endpoint requires both leagueId and season query parameters to be specified before you can fetch the data.

Below is an example on how you could render league associated standings