1. Introduction

Sportef API is organized around REST. Our API is designed to have predictable, All calls are made with HTTP/HTTPS and JSON will be returned in all responses from the API, Including errors.
We support cross-origin resource sharing to allow you to interact securely with our API from a server-side web application (though you should remember that you should never expose your secret API key in any public website's client-side code).


1.1 API Endpoint

https://api.sportef.com/

Both HTTP and HTTPS protocols are supported.


1.2 Supported Languages

Language Code
Englishen
Arabicar

1.3 Supported HTTP Request Methods

  • GET
  • POST

1.4 HTTP Response Codes

Sportef uses conventional HTTP response codes to indicate success or failure of an API request.
In general, codes in the 2xx range indicate success, codes in the 4xx and 5xx range indicate an error that resulted from the provided information. Error messages will also return in JSON format.

Code Description
200Everything worked as expected.
400Bad Request.
401Unauthorized.
403Forbidden.
404Not Found.
405Method Not Allowed.

Sample response

{"error_code": "4xx","msg": "Error Message"}

1.5 Standard Parameters

https://api.sportef.com/:lang/:version/:http_method/:method/?api_key=:api_key

Parameter Data type Possible values
lang string
  • en (English)
  • ar (Arabic)
version string v1.0
http_method string
  • get
  • post
method string One of supported methods, such as countries.get_list .. etc
api_key string Valid API-Key, you can manage your APIs from Account Subscriptions.

2. Authentication

All Sportef API methods require authentication by using an API-key.
Every plan has an API-Key, You can manage your API keys from your Account Subscriptions.

3. Countries

The countries API lets you retrieve countries details such as country_id, country_name ..etc.

Glossary:
Name Data type Description
country_id integer Unique country id
country_name string Country name
code string Two letter country code in ISO 3166-1 Alpha 2 format
parent_id integer Continent country id

3.1 countries.get_list

Request:
Parameter Data type Requirements Description
hierarchy integer Optional Possible values: 0, 1
Default: 0
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/countries.get_list/?api_key=:api_key&hierarchy=1

curl "https://api.sportef.com/v1.0/post/countries.get_list/" -d "api_key=:api_key&hierarchy=1"

Sample Response:

4. Competitions

The competitions API lets you retrieve competitions details such as country_id, country_name ..etc.

Glossary:
Name Data type Description
competition_id integer Unique competition id
competition_name string Competition name
country_id integer Unique country id
country_name string Country name
code string Two letter country code in ISO 3166-1 Alpha 2 format
current_season object Details about current competition season

Competitions list and details, depends on your subscription.

4.1 competitions.get_list

Parameter Data type Requirements Description
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/competitions.get_list/?api_key=:api_key

curl "https://api.sportef.com/v1.0/post/competitions.get_list/" -d "api_key=:api_key"

Sample Response:

4.2 competitions.by_country

Parameter Data type Requirements Description
country_id integer Required Valid country_id, See Countries
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/competitions.by_country/?api_key=:api_key&country_id=1

curl "https://api.sportef.com/v1.0/post/competitions.by_country/" -d "api_key=:api_key&country_id=1"

Sample Response:

4.2 competitions.competition

Parameter Data type Requirements Description
competition_id integer Required Valid competition_id, See Competitions
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/competitions.competition/?api_key=:api_key&competition_id=1

curl "https://api.sportef.com/v1.0/post/competitions.competition/" -d "api_key=:api_key&competition_id=1"

Sample Response:

4.2 competitions.top_scorers

Get top scorers for current season in a specified competition

Parameter Data type Requirements Description
competition_id integer Required Valid competition_id, See Competitions
Examples:

https://api.sportef.com/v1.0/get/competitions.top_scorers/?api_key=:api_key&competition_id=18

curl "https://api.sportef.com/v1.0/post/competitions.top_scorers/" -d "api_key=:api_key&competition_id=18"

Sample Response:

5. Seasons

The seasons API lets you retrieve seasons details such as country_id, country_name ..etc.

Glossary:
Name Data type Description
season_id integer Unique season id
season_name string Season name
start_date date Season start date
end_date date Season end date
is_active integer 0 if season end, 1 if season is active or upcoming

Seasons list and details, depends on your subscription.
Old data will be returned if your subscription includes historical data, otherwise only active seasons will be returned.

5.1 seasons.get_list

Parameter Data type Requirements Description
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/seasons.get_list/?api_key=:api_key

curl "https://api.sportef.com/v1.0/post/seasons.get_list/" -d "api_key=:api_key"

Sample Response:

5.2 seasons.by_competition

Parameter Data type Requirements Description
competition_id integer Required Valid competition_id, See Competitions
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/seasons.by_competition/?api_key=:api_key&competition_id=1

curl "https://api.sportef.com/v1.0/post/seasons.by_competition/" -d "api_key=:api_key&competition_id=1"

Sample Response:

5.3 seasons.by_team

Parameter Data type Requirements Description
team_id integer Required Valid team_id, See Teams
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/seasons.by_team/?api_key=:api_key&team_id=21

curl "https://api.sportef.com/v1.0/post/seasons.by_team/" -d "api_key=:api_key&team_id=21"

Sample Response:

5.4 seasons.standing

Parameter Data type Requirements Description
season_id integer Required Valid season_id
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/seasons.standing/?api_key=:api_key&season_id=127

curl "https://api.sportef.com/v1.0/post/seasons.standing/" -d "api_key=:api_key&season_id=20"

Sample Response:

Sample 1

Sample 2

5.5 seasons.rounds

Parameter Data type Requirements Description
season_id integer Required Valid season_id
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/seasons.rounds/?api_key=:api_key&season_id=20

curl "https://api.sportef.com/v1.0/post/seasons.rounds/" -d "api_key=:api_key&season_id=20"

Sample Response:

5.6 seasons.top_scorers

Parameter Data type Requirements Description
season_id integer Required Valid season_id
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/seasons.top_scorers/?api_key=:api_key&season_id=127

curl "https://api.sportef.com/v1.0/post/seasons.top_scorers/" -d "api_key=:api_key&season_id=127"

Sample Response:

5.7 seasons.season

Parameter Data type Requirements Description
season_id integer Required Valid season_id
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/seasons.season/?api_key=:api_key&season_id=21

curl "https://api.sportef.com/v1.0/post/seasons.season/" -d "api_key=:api_key&season_id=21"

Sample Response:

6. Matches

The matches API lets you retrieve matches details.

Glossary:
Name Data type Description
match_id integer Unique match id
date_utc date Match date in UTC
status integer
  • 1 Playing
  • 2 Scheduled
  • 3 Postponed
  • 4 Suspended
  • 5 Played
  • 6 Cancelled
f1 integer Full-time goals for team 1
h1 integer Half-time goals for team 1
e1 integer Extra-time goals for team 1
p1 integer Goals scored in penalty shootout, after match ended with draw result.
team_1_goals integer All Goals for team 1 in the match
minute integer Current match minute if its playing now (status=1)
extra_minutes integer Match extra time
period string Match period if its playing now:
  • 1H First Half
  • 2H Second Half
  • HT Half time
  • E1 Extra time for first half
  • E2 Extra time for second half
  • EH Extra time break
  • PS Penalty shootout
  • FT Fulltime

Match details depends on your subscription.
Old data will be returned if your subscription includes historical data, otherwise only matches in active seasons will be returned.

6.1 matches.now

Parameter Data type Requirements Description
display string Optional Possible values: list, competition
Default: list
Examples:

https://api.sportef.com/v1.0/get/matches.now/?api_key=:api_key

curl "https://api.sportef.com/v1.0/post/matches.now/" -d "api_key=:api_key"

Sample Response:

6.2 matches.today

Parameter Data type Requirements Description
display string Optional Possible values: list, competition
Default: list
Examples:

https://api.sportef.com/v1.0/get/matches.today/?api_key=:api_key

curl "https://api.sportef.com/v1.0/post/matches.today/" -d "api_key=:api_key"

Sample Response:

6.3 matches.yesterday

Parameter Data type Requirements Description
display string Optional Possible values: list, competition
Default: list
Examples:

https://api.sportef.com/v1.0/get/matches.yesterday/?api_key=:api_key

curl "https://api.sportef.com/v1.0/post/matches.yesterday/" -d "api_key=:api_key"

6.4 matches.tomorrow

Parameter Data type Requirements Description
display string Optional Possible values: list, competition
Default: list
Examples:

https://api.sportef.com/v1.0/get/matches.tomorrow/?api_key=:api_key

curl "https://api.sportef.com/v1.0/post/matches.tomorrow/" -d "api_key=:api_key"

6.5 matches.by_date

Parameter Data type Requirements Description
date date Required Format: YYYY-mm-dd
UTC date
display string Optional Possible values: list, competition
Default: list
Examples:

https://api.sportef.com/v1.0/get/matches.by_date/?api_key=:api_key&date=2017-01-17

curl "https://api.sportef.com/v1.0/post/matches.by_date/" -d "api_key=:api_key&date=2017-01-17"

6.6 matches.by_date_range

Parameter Data type Requirements Description
from date Required Format: YYYY-mm-dd
UTC date
to date Required Format: YYYY-mm-dd
Maximum 7 days between from and to dates
display string Optional Possible values: list, competition
Default: list
Examples:

https://api.sportef.com/v1.0/get/matches.by_date_range/?api_key=:api_key&from=2017-01-01&to=2017-01-05

curl "https://api.sportef.com/v1.0/post/matches.by_date_range/" -d "api_key=:api_key&from=2017-01-01&to=2017-01-05"

6.7 matches.by_competition

Parameter Data type Requirements Description
competition_id integer Required Valid competition_id, See Competitions
Examples:

https://api.sportef.com/v1.0/get/matches.by_competition/?api_key=:api_key&competition_id=18

curl "https://api.sportef.com/v1.0/post/matches.by_competition/" -d "api_key=:api_key&competition_id=18"

6.8 matches.by_season

Parameter Data type Requirements Description
season_id integer Required Valid season_id, See Seasons
Examples:

https://api.sportef.com/v1.0/get/matches.by_season/?api_key=:api_key&season_id=139

curl "https://api.sportef.com/v1.0/post/matches.by_season/" -d "api_key=:api_key&season_id=139"

6.9 matches.by_team

Parameter Data type Requirements Description
team_id integer Required Valid team_id, See Teams
status integer Optional Match status
from date Optional Format: YYYY-mm-dd
UTC date
to date Optional Format: YYYY-mm-dd
UTC date
competition_id integer Optional Valid competition_id
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/matches.by_team/?api_key=:api_key&team_id=139

curl "https://api.sportef.com/v1.0/post/matches.by_team/" -d "api_key=:api_key&team_id=139"

6.10 matches.match

Glossary:
Name Data type Description
team_1_coach_id integer Unique coach id for team 1
team_1_coach_name string Team 1 coach name
referee_id integer Unique match referee id
referee_name string Match referee name
stadium_id integer Unique stadium id
stadium_name string Stadium name
code
event code
integer
  • 1 Goal Assist
  • 2 Line-Up
  • 3 Own Goal
  • 4 Plenty Goal
  • 5 Plenty Shot
  • 6 Plenty Shot Goal
  • 7 Plenty Shot Missed
  • 8 Red Card
  • 9 Substitution In
  • 10 Substitution Out
  • 11 Player on bench
  • 12 Second yellow card (Red Card)
  • 13 Yellow card
  • 14 Goal
  • 15 Plenty Missed
minute integer Event minute
Parameter Data type Requirements Description
match_id integer Required Valid match_id
Examples:

https://api.sportef.com/v1.0/get/matches.match/?api_key=:api_key&match_id=237779

curl "https://api.sportef.com/v1.0/post/matches.match/" -d "api_key=:api_key&match_id=237779"

Sample Response:

7. Teams

Glossary:
Name Data type Description
team_id integer Unique team id
team_name string Team name
tcode string Three Letter Team Code
team_type integer
  • 1 National Team
  • 2 Club
team_images object Team logo in different sizes

7.1 teams.by_season

Request:
Parameter Data type Requirements Description
season_id integer Required Valid season_id, See Seasons
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/teams.by_season/?api_key=:api_key&season_id=20

curl "https://api.sportef.com/v1.0/post/teams.by_season/" -d "api_key=:api_key&season_id=20"

Sample Response:

7.2 teams.by_country

Request:
Parameter Data type Requirements Description
country_id integer Required Valid country_id, See Countries
page integer Optional Possible values: 1 >= and <= pages
Default: 1
Examples:

https://api.sportef.com/v1.0/get/teams.by_country/?api_key=:api_key&country_id=207

curl "https://api.sportef.com/v1.0/post/teams.by_country/" -d "api_key=:api_key&country_id=207"

7.3 teams.players

Glossary:
Name Data type Description
player_id integer Unique player id
player_id string Player name
date_of_birth date Player date of birth (YYYY-mm-dd)
height integer Player height in CM
weight integer Player weight in KG
position integer
  • 1 Attacker
  • 2 Defender
  • 3 Goalkeeper
  • 4 Midfielder
  • 5 Unknown
player_images object Player images in different sizes
nationality_country_id integer Player nationality id See Countries
nationality_country_name string Player nationality name See Countries
nationality_code string Two letter player nationality code in ISO 3166-1 Alpha 2 format See Countries
Request:
Parameter Data type Requirements Description
team_id integer Required Valid team_id, See Teams
season_id integer Required Valid season_id, See Seasons
Examples:

https://api.sportef.com/v1.0/get/teams.players/?api_key=:api_key&team_id=20&season_id=1637

curl "https://api.sportef.com/v1.0/post/teams.players/" -d "api_key=:api_key&team_id=20&season_id=1637"

Sample Response:

8. Players

8.1 players.by_team

This API is alias of teams.players