Handball API / highlights

Get geo restrictions for a highlight

GET https://handball.highlightly.net/highlights/geo-restrictions/{id} Handball API
GET https://sports.highlightly.net/handball/highlights/geo-restrictions/{id} All Sports API

Geo restrictions limit access to online content based on where the viewer is. Showing a restricted clip to someone who cannot play it is a poor experience, so check the restrictions before rendering a highlight to a given audience.

Refresh interval
Once an hour
Plan
Not available on Basic/Free

Restriction states

The state field says which rule applies to the highlight, and therefore which of the two country lists you should read.

state What to do
No restricitons applied The highlight is available globally. Both country lists can be ignored.
Allowed countries restriction Show the highlight only to viewers whose country code appears in allowedCountries.
Blocked countries restriction Hide the highlight from viewers whose country code appears in blockedCountries. Everyone else may watch.
Unknown restrictions There is no guaranteed way to determine the allowed or blocked set.

Both lists hold ISO 3166 two letter country codes, such as IT.

Embedding

Whether the hosting platform permits embedding is a separate question from geography, and embeddable on this response answers it.

The video URLs themselves are not here. embedUrl and url live on the highlight, from highlights or get highlight by ID. So the usual sequence is to read the highlight for its URLs, then read this endpoint to decide whether to frame embedUrl or link out to url.

A highlight can be viewable in a country and still not be embeddable, since embeddable applies to the highlight as a whole.

Parameters

Parameter Type Description
idrequired numberpath Requested highlight id.

Request

curl --request GET \
  --url 'https://handball.highlightly.net/highlights/geo-restrictions/{id}' \
  --header 'x-rapidapi-key: YOUR_API_KEY'
const response = await fetch('https://handball.highlightly.net/highlights/geo-restrictions/{id}', {
  headers: {
    'x-rapidapi-key': process.env.HIGHLIGHTLY_API_KEY
  }
})

if (!response.ok) {
  throw new Error(`Highlightly responded ${response.status}`)
}

const data = await response.json()
import os
import requests

response = requests.get(
    'https://handball.highlightly.net/highlights/geo-restrictions/{id}',
    headers={
        'x-rapidapi-key': os.environ['HIGHLIGHTLY_API_KEY'],
    },
    timeout=10,
)

response.raise_for_status()
data = response.json()

Response

statestringrequiredSpecifies which restriction rule is applied to the requested highlight. If allowed restriction is applied, read from allowedCountries field. When blocked restriction is applied, countries from blockedCountries field are applied.No restricitons appliedAllowed countries restrictionBlocked countries restrictionUnknown restrictions
allowedCountriesstring[]requiredISO 3166 two letter country list of allowed countries when restriction rules is in allowed state.
blockedCountriesstring[]requiredISO 3166 two letter country list of blocked countries. Rule list is valid when restriction rules is in blocked state.
embeddablebooleanrequiredBoolean flag which indicates whether highlight provider allows embedding inside web applications.

Example response

200 application/json 
{
  "state": "Allowed countries restriction",
  "allowedCountries": [
    "IT"
  ],
  "blockedCountries": [],
  "embeddable": true
}

Values are the examples declared in the OpenAPI spec, not a captured live response.

Errors

Status Description
400 Bad request descriptive error.
500 Internal server error.