Football API / highlights

Get geo restrictions for a highlight

GET https://soccer.highlightly.net/highlights/geo-restrictions/{id} Football API
GET https://sports.highlightly.net/football/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 Meaning
No restricitons applied The highlight has no restrictions applied and is available globally.
Allowed countries restriction The highlight is only available to viewers whose country code appears in allowedCountries.
Blocked countries restriction The highlight is blocked for viewers whose country code appears in blockedCountries.
Unknown restrictions There is no guaranteed way to define all allowed or blocked countries.

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://soccer.highlightly.net/highlights/geo-restrictions/{id}' \
  --header 'x-rapidapi-key: YOUR_API_KEY'
const response = await fetch('https://soccer.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://soccer.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.