Football API / matches

Get match by ID

GET https://soccer.highlightly.net/matches/{id} Football API
GET https://sports.highlightly.net/football/matches/{id} All Sports API

Retrieve detailed information for one match.

This is the detail view. Matches returns general information for a list of fixtures, and this route fills in everything that route leaves out.

Predictions

When present, predictions holds two lists, prematch and live.

Each prediction carries its type, the modelType, when it was generatedAt, a written description, and the probabilities. Those always carry home and away, and draw is optional.

Each prediction carries its own generatedAt timestamp, so read it to know when a forecast was produced.

Event types

Type Meaning
Goal A player strikes the ball into the opposing team's goal.
Own Goal A player strikes or deflects the ball into their own team's goal.
Penalty A goal scored from the penalty spot after a foul or handball by the defending team inside the area.
Missed Penalty The penalty taker failed to score, either missing the target or being saved.
Yellow Card A player is cautioned for unsporting behaviour or foul play.
Red Card A player is sent off for serious foul play, violent conduct, or a second yellow.
Substitution A player is replaced from the bench during a stoppage.
VAR Goal Confirmed Video review confirms a goal is valid and stands.
VAR Goal Cancelled Video review disallows a goal for an infringement.
VAR Goal Cancelled - Offside Video review disallows a goal for offside.
VAR Penalty Video review awards a penalty.
VAR Penalty Cancelled Video review overturns a penalty already awarded.

Parameters

Parameter Type Description
idrequired numberpath Requested match id.

Request

curl --request GET \
  --url 'https://soccer.highlightly.net/matches/{id}' \
  --header 'x-rapidapi-key: YOUR_API_KEY'
const response = await fetch('https://soccer.highlightly.net/matches/{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/matches/{id}',
    headers={
        'x-rapidapi-key': os.environ['HIGHLIGHTLY_API_KEY'],
    },
    timeout=10,
)

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

Response

idnumberrequired
roundstringrequired
datestringrequired
countryCountryResponserequired3 fields
codestringrequiredCountry code specified by the ISO 3166 standard.
namestringrequired
logostringrequired
awayTeamDetailedTeamResponserequired14 fields
idnumberrequired
logostring
namestringrequired
shotsShots[]4 fields
playerNamestringrequired
timestringrequired
outcomestringrequired
goalTargetstringrequired
topPlayersTopPlayersResponse[]5 fields
positionstringrequired
namestringrequired
statisticsTopPlayerStatisticsResponse[]required2 fields
namestringrequired
valueobjectrequired
homeTeamDetailedTeamResponserequired14 fields
idnumberrequired
logostring
namestringrequired
shotsShots[]4 fields
playerNamestringrequired
timestringrequired
outcomestringrequired
goalTargetstringrequired
topPlayersTopPlayersResponse[]5 fields
positionstringrequired
namestringrequired
statisticsTopPlayerStatisticsResponse[]required2 fields
namestringrequired
valueobjectrequired
leagueMatchLeagueResponserequired4 fields
idnumberrequired
seasonnumberrequired
namestringrequired
logostring
stateMatchStateResponserequired5 fields
descriptionstringrequiredState of the match.To be announcedNot startedFirst halfHalf timeSecond halfExtra timeBreak timePenaltiesSuspendedInterruptedFinishedFinished after penaltiesFinished after extra timePostponedCancelledAbandonedAwardedIn progressUnknown
clocknumberCurrent minute of the match.
scoreMatchScoreResponserequired2 fields
currentstringHome - Away score up to penalties.
penaltiesstringHome - Away team score after the penalties phase.
eventsLiveEvent[]required11 fields
teamLiveEventTeamrequired3 fields
idnumberrequired
logostring
namestringrequired
timestringrequired
typestringrequiredGoalOwn GoalPenaltyMissed PenaltyYellow CardRed CardSubstitutionVAR Goal ConfirmedVAR Goal CancelledVAR PenaltyVAR Penalty CancelledVAR Goal Cancelled - Offside
playerIdnumber
playerstring
assistingPlayerIdnumber
assiststring
substitutedstring
statisticsMatchStatisticsResponse[]required8 fields
teamTeamResponserequired4 fields
idnumberrequired
logostring
namestringrequired
typestringclubnational
statisticsMatchStatisticsResponseItem[]required2 fields
valuenumberrequired
displayNamestringrequired
refereeDetailedMatchRefereeResponse2 fields
namestring
nationalitystring
venueDetailedMatchVenueResponse4 fields
citystring
namestring
countrystring
capacitystring
forecastDetailedMatchForecastResponse2 fields
statusstring
temperaturestring
predictionsPredictionResponse18 fields
prematchPrediction[]required8 fields
typestringrequired
modelTypestringrequired
generatedAtstringrequired
descriptionstringrequired
probabilitiesPredictionProbabilitiesrequired3 fields
homestringrequired
drawstring
awaystringrequired
livePrediction[]required8 fields
typestringrequired
modelTypestringrequired
generatedAtstringrequired
descriptionstringrequired
probabilitiesPredictionProbabilitiesrequired3 fields
homestringrequired
drawstring
awaystringrequired
newsNews[]4 fields
urlstringrequired
imagestringrequired
titlestringrequired
datePublishedstringrequired

Example response

200 application/json 
[
  {
    "id": 1002433681,
    "round": "Apertura - 9",
    "date": "\"2024-03-31T20:30:00.000Z",
    "country": {
      "code": "FR",
      "name": "France",
      "logo": "https://example.com/logos/country/FR.png"
    },
    "awayTeam": {
      "id": 553,
      "logo": "https://example.com/logos/team/553.png",
      "name": "Montpellier",
      "shots": [
        {
          "playerName": "Cody Gakpo",
          "time": "3'",
          "outcome": "Missed",
          "goalTarget": "High Right"
        }
      ],
      "topPlayers": [
        {
          "position": "Midfielder",
          "name": "Carlos Augusto",
          "statistics": [
            {
              "name": "Shots On Target",
              "value": 2
            }
          ]
        }
      ]
    },
    "homeTeam": {
      "id": 553,
      "logo": "https://example.com/logos/team/553.png",
      "name": "Montpellier",
      "shots": [
        {
          "playerName": "Cody Gakpo",
          "time": "3'",
          "outcome": "Missed",
          "goalTarget": "High Right"
        }
      ],
      "topPlayers": [
        {
          "position": "Midfielder",
          "name": "Carlos Augusto",
          "statistics": [
            {
              "name": "Shots On Target",
              "value": 2
            }
          ]
        }
      ]
    },
    "league": {
      "id": 133,
      "season": 2023,
      "name": "Ligue 1",
      "logo": "https://example.com/logos/league/133.png"
    },
    "state": {
      "description": "Second half",
      "clock": 67,
      "score": {
        "current": "3 - 1",
        "penalties": "6 - 4"
      }
    },
    "events": [
      {
        "team": {
          "id": 13394673,
          "logo": "https://example.com/logo/preview/66311.13394673",
          "name": "Tersana"
        },
        "time": "45+1",
        "type": "Goal",
        "playerId": 63606907,
        "player": "M. Mamdouh",
        "assistingPlayerId": 0,
        "assist": "J. Johanson",
        "substituted": ""
      }
    ],
    "statistics": [
      {
        "team": {
          "id": 553,
          "logo": "https://example.com/logos/team/553.png",
          "name": "Montpellier",
          "type": "club"
        },
        "statistics": [
          {
            "value": 0.62,
            "displayName": "Shots accuracy"
          }
        ]
      }
    ],
    "referee": {
      "name": "Brace, Andrew",
      "nationality": "Ireland"
    },
    "venue": {
      "city": "Swansea",
      "name": "Liberty Stadium",
      "country": "Wales",
      "capacity": "20827"
    },
    "forecast": {
      "status": "cloudy",
      "temperature": "11.97°C"
    },
    "predictions": {
      "prematch": [
        {
          "type": "prematch",
          "modelType": "three-way",
          "generatedAt": "2025-03-12T19:00:20.000Z",
          "description": "Team A is most likely to win the game against Team B.`",
          "probabilities": {
            "home": "30.22%",
            "draw": "0.00%",
            "away": "69.78%"
          }
        }
      ],
      "live": [
        {
          "type": "prematch",
          "modelType": "three-way",
          "generatedAt": "2025-03-12T19:00:20.000Z",
          "description": "Team A is most likely to win the game against Team B.`",
          "probabilities": {
            "home": "30.22%",
            "draw": "0.00%",
            "away": "69.78%"
          }
        }
      ]
    },
    "news": [
      {
        "url": "https://football-italia.net/watch-milan-reijnders-scores-16th-goal-2024-25/?utm_source=365Scores&utm_medium=link&utm_campaign=Contact%2bus%2bat%2b365scores%2bfor%2bmore%2btraffic",
        "image": "https://icdn.football-italia.net/wp-content/uploads/2025/03/netherlands-v-spain-uefa-nations.jpg",
        "title": "Celebrating Fernando Torres: A Spanish Football Icon",
        "datePublished": "2025-03-20T19:29:02Z"
      }
    ]
  }
]

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.