JSON API Documentation

Удостоверяване

Удостоверяването се извършва посредством API Key, който се генерира специално за вашия сайт.

Може да заявите вашия API Key на следния email: api@bgclubs.eu

Въведете вашия API key като X-GOALBG-Key хедър:

curl -H "X-GOALBG-Key: {api_key}" https://api.goal.bg/v2/…

Примерен PHP код

$url = 'https://api.goal.bg/v2/standings.json?tournament_id=1000000'
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 2);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-GOALBG-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'));
$result = @curl_exec($ch);
curl_close($ch);

Резултат

Хедъри

X-RateLimit-Limit Общият брой заявки, които можете да направите.
X-RateLimit-Remaining Оставащият брой заявки, които можете да направите.
X-RateLimit-Reset Оставащото време до нулиране на ограничението на заявките.

Грешки

401 API key not provided Не е предоставен ключ за удостоверяване.
401 API key not valid Предоставеният ключ за удостоверяване не е валиден.
401 API key not found Предоставеният ключ за удостоверяване не е регистриран.
403 Inactive Account Достъп до ресурс, който съществува, но не е достъпен.
403 Access denied Достъп до ресурс, който съществува, но не е достъпен.
404 Not Found Достъп до ресурс, който не съществува.
405 Method Not Allowed Не е разрешен метода за достъп до ресурса.
429 Rate limit exceeded Превишен е лимита на направените заявки.

Ресурси

Статус

/status.json

GET ТЕСТ 
{
    "GET": "Status",
    "response": {
        "account": {
            "user": "Test API",
            "email": "api@bgclubs.eu"
        },
        "subscription": {
            "plan": "TEST",
            "end": "2022-04-10 23:59:59",
            "active": true
        },
        "requests": {
            "limit": 1000,
            "current": 12
        }
    }
}

Сезони

/seasons.json

GET ТЕСТ 
{
    "GET": "Seasons",
    "parameters": [ ... ],
    "count": 28,
    "response": [
        {
            "id": 221,
            "key": "2020-2021",
            "name": "2020/2021",
            "current": true
        },
        {
            "id": 220,
            "key": "2019-2020",
            "name": "2019/2020",
            "current": false
        },
        ...
        {
            "id": 148,
            "key": "1948-1949",
            "name": "1948/1949",
            "current": false
        }
    ]
}

Филтри

Name Type Default Description
season_id optional integer
{\d\d\d}		 - ID на сезона
current optional boolean
 		 - Текущ сезон

Турнири

/tournaments.json

GET ТЕСТ 
{
    "GET": "Tournaments",
    "parameters": [ ... ],
    "count": 162,
    "response": [
        {
            "id": 1000000,
            "name": "Първа професионална лига",
            "level": "MEN",
            "phases": [
                {
                    "id": 100,
                    "name": "Първа фаза",
                    "type": "LEAGUE"
                },
                {
                    "id": 200,
                    "name": "Втора фаза",
                    "type": "LEAGUE"
                }
            ]
        },
        {
            "id": 2000000,
            "name": "Втора професионална лига",
            "level": "MEN",
            "phases": [
                {
                    "id": 100,
                    "name": null,
                    "type": "LEAGUE"
                }
            ]
        },
        ...
        {
            "id": 8090101,
            "name": "Държавно първенство за жени",
            "level": "WOMEN",
            "phases": [
                {
                    "id": 100,
                    "name": null,
                    "type": "LEAGUE"
                }
            ]
        }
    ]
}

Филтри

Name Type Default Description
season_id optional integer
{\d\d\d}		 224
{current}		 ID на сезона
tournament_id optional integer
{\d\d\d\d\d\d\d}		 - ID на трурнира
phase_id optional integer
{\d\d\d}		 - ID на фазата
level optional enum
{MEN|YOUTH|WOMEN|GIRLS}		 - Ниво на турнира
type optional enum
{LEAGUE|ELIMINATION|ROUND_ROBIN|FRIENDLIES}		 - Тип на фазата

Клубове

/clubs.json

GET ТЕСТ 
{
    "GET": "Clubs",
    "parameters": [ ... ],
    "count": 863,
    "response": [
        {
            "id": 10103,
            "key": "Levski(Sofia)",
            "name": "Левски (София)",
            "link": "http://bgclubs.eu/teams/Levski(Sofia)",
            "logo": "https://api.goal.bg/logos/100/10103.png",
            "active": true
        },
        ...
        {
            "id": 10168,
            "key": "Vladislav(Varna)",
            "name": "Владислав (Варна)",
            "link": "http://bgclubs.eu/teams/Vladislav(Varna)",
            "logo": "https://api.goal.bg/logos/100/10168.png",
            "active": false
        }
    ]
}

Филтри

Name Type Default Description
club_id optional integer
{\d\d\d\d\d}		 - ID на клуба
name optional string
 		 - Име на клуба
active optional boolean
 		 true Активен ли е клубът

Отбори

/teams.json

GET ТЕСТ 
{
    "GET": "Teams",
    "parameters": [ ... ],
    "count": 13,
    "response": [
        {
            "id": "10103-111",
            "name": "Левски (София)",
            "shortName": null,
            "team": "Първи отбор"
        },
        {
            "id": "10103-351",
            "name": "Левски (София)",
            "shortName": null,
            "team": "Юноши старша"
        },
        ...
        {
            "id": "10103-492",
            "name": "Левски II (София)",
            "shortName": null,
            "team": "Подготвителна група до 9 години II"
        }
    ]
}

Филтри

Name Type Default Description
season_id optional integer
{\d\d\d}		 224
{current}		 ID на сезона
club_id required integer
{\d\d\d\d\d}		 - ID на клуба

Мачове

/matches.json

GET ТЕСТ 
{
    "GET": "Matches",
    "parameters": [ ... ],
    "count": 240,
    "response": [
        {
            "id": 140189,
            "type": "REGULAR",
            "season": {
                "id": 221,
                "key": "2020-2021",
                "name": "2020/2021"
            },
            "tournament": {
                "id": 1000000,
                "name": "Първа професионална лига",
                "phase": {
                    "id": 100,
                    "name": "Първа фаза",
                    "type": "LEAGUE"
                },
                "link": "https://bulgarian-football.com/parva-liga.html#a-f"
            },
            "round": 15,
            "date": "2020-12-05",
            "time": "14:15",
            "status": "FINISHED",
            "stats": "https://bulgarian-football.com/stats/a15.html#2",
            "tv": "Диема спорт",
            "homeTeam": {
                "id": "11341-111",
                "key": "FKCSKA1948(Sofia)",
                "name": "ФК ЦСКА 1948 (София)",
                "shortName": null,
                "link": "http://bgclubs.eu/teams/FKCSKA1948(Sofia)",
                "logo": "https://api.goal.bg/logos/25/11341.png"
            },
            "awayTeam":{
                "id": "10115-111",
                "key": "Beroe(StaraZagora)",
                "name": "Берое (Стара Загора)",
                "shortName": null,
                "link": "http://bgclubs.eu/teams/Beroe(StaraZagora)",
                "logo": "https://api.goal.bg/logos/25/10115.png"
            },
            "score": {
                "winner": "HOME_TEAM",
                "duration": "REGULAR",
                "fullTime": {
                    "homeTeam": 1,
                    "awayTeam": 0
                },
                "halfTime": {
                    "homeTeam": 0,
                    "awayTeam": 0
                },
                "extraTime": {
                    "homeTeam": null,
                    "awayTeam": null
                },
                "penalties": {
                    "homeTeam": null,
                    "awayTeam": null
                },
                "awarded": false
            },
            "related": null,
            "lastUpdatedAt": "2020-12-05 16:19:15"
        },
        ...
        {
            ...
        }     
    ]
}

Филтри

Name Type Default Description
season_id optional integer
{\d\d\d}		 224
{current}		 ID на сезона
tournament_id required* integer
{\d\d\d\d\d\d\d}		 - ID на трурнира
phase_id optional integer
{\d\d\d}		 - ID на фазата
team_id required* string
{\d\d\d\d\d-\d\d\d}		 - ID на отбора
round optional integer
{1 - 44}		 - Кръгът на мача
date required* date
{YYYY-MM-DD}		 - Дата на мача
last optional integer
{1 - 20}		 - За последните X мача
next optional integer
{1 - 20}		 - За следващите X мача
status optional list
 		 - Статус на мача:
FINISHED - приключил (има резултат)
SCHEDULED - насрочен е (има дата и час)
NOT_SCHEDULED - не е насрочен (няма дата или час)
CANCELLED - анулиран
BROUGHT_FORWARD - изтеглен, проведен на предходна дата
POSTPONED - отложен, проведен на последваща дата
ABANDONED - прекратен, доигран на нова дата
ANNULLED - анулиран, преигран на нова дата
NOT_COUNTED - неофициален мач, извън класирането
TEAM_BYE - отборът почива в този кръг

Технически

Name Type Default Description
_sort optional list
{tournament_id|phase_id|round|datetime|id}		 - Сортиране
_limit optional integer
{1 - 500}		 500 Брой върнати резултата
_offset optional integer
{0 - 999999}		 0 Брой пропуснати резултата

Примери

 #Връща само мачовете с въведен резултат и/или насрочена дата от избрания турнир.
 get("https://api.goal.bg/v2/matches.json?tournament_id=1000000&status=FINISHED,SCHEDULED")
  
 #Връща мачовете от избрания турнир, сортирани по кръг и след това по дата в обратен ред.
 get("https://api.goal.bg/v2/matches.json?tournament_id=1000000&_sort=round,-datetime")
 
 #Връща извадка от 20 мача за избрания турнир, обхващаща интервала от 21-и до 40-и мач.
 get("https://api.goal.bg/v2/matches.json?tournament_id=1000000&_limit=20&_offset=20")
 
 #Връща последните 10 мача за избрания турнир.
 get("https://api.goal.bg/v2/matches.json?tournament_id=1000000&last=10")
 
 #Връща следващия мач за избрания отбор.
 get("https://api.goal.bg/v2/matches.json?team_id=10103-111&next=1")

Класиране

/standings.json

GET ТЕСТ 
{
    "GET": "Standings",
    "parameters": [ ... ],
    "count": 1,
    "response": [
        {
            "season": {
                "id": "221",
                "key": "2020-2021",
                "name": "2020/2021"
            },
            "tournament": {
                "id": "1000000",
                "name": "Първа професионална лига",
                "phase": {
                    "id": "100",
                    "name": "Първа фаза",
                    "type": "LEAGUE"
                },
                "link": "https://bulgarian-football.com/parva-liga.html#a-f"
            },
            "TOP1": [],
            "TOP2": [],
            "BOTTOM2": [],
            "BOTTOM1": [],
            "promoted": [],
            "relegated": [],
            "moved": [],
            "noteMarker": [],
            "notes": "",
            "order": "order4",
            "standings": [
                {
                    "position": 1,
                    "team":{
                        "id":"10228-111",
                        "key":"Ludogorets1945(Razgrad)",
                        "name":"Лудогорец 1945 (Разград)",
                        "shortName":"Лудогорец 1945 (Рз)",
                        "link":"http://bgclubs.eu/teams/Ludogorets1945(Razgrad)",
                        "logo":"https://api.goal.bg/logos/25/10228.png"
                    },
                    "playedGames": "23",
                    "wins": "19",
                    "draws": "3",
                    "losses": "1",
                    "goalsFor": "60",
                    "goalsAgainst": "17",
                    "goalDifference": "43",
                    "points": "60",
                    "status": "TOP2",
                    "description": "Първи 6"
                },
                ...
                {
                    ...
                }
            ],
            "lastUpdatedAt": "2020-10-05 20:00:00"
        }
    ]
}

Филтри

Name Type Default Description
season_id optional integer
{\d\d\d}		 224
{current}		 ID на сезона
tournament_id required integer
{\d\d\d\d\d\d\d}		 - ID на трурнира
phase_id optional integer
{\d\d\d}		 - ID на фазата