SoccerGames

SoccerGames datasource lets you create subscriptions for the next soccer games and results. With Hooks Query Language you can customize what data and when you want to receive:

Input Output Credits Freshness
SoccerGame 1 minute

What you can get from this API

  • Get an update when a team starts or ends a game with a score and other SoccerGame data.
  • Get an update when a team wins a game or ends a game with a score.
  • Get an update when a team wins a game by 2 goals.
  • Get all the games for a soccer team.

How to Use

As every datasource at Hooks, you can choose to pull the data in your preferred format or to set up a webhook to receive the data when something happens.  

As we offer many datasources, we have developed a custom SQL-Like language (Hooks Query Language) to be able to query each datasource in the same format. To create a subscription the first thing you need to do is to define an HQL query and then send this query to create subscription endpoint.

SoccerGames datasource has no mandatory parameters and you can use an optional WHERE clause to filter the output data (SoccerGame) in order to receive just what you need. Hooks will then call your webhook once new data is available for your query. 

Step 1: Customize subscription

DHooks provide an elegant mechanism for creating subscriptions using Hooks Query Language. It has a similar notation to SQL and lets you define each subscription with a simple HQL query.

The following query will create a subscription to “Send me updates for all Real Madrid games 1 hour before the start”:

SELECT * FROM SoccerGames 
WHERE away_team.team_name = 'Real Madrid' 
OR home_team.team_name = 'Real Madrid' 
AND start_datetime.countdown = 3600

Once this HQL query has new results -1 hour before Real Madrid plays a new game – Hooks will send SoccerGame object to your webhook:

{
    "matches_count": 1,
    "results": [
        {
            "_entity_type": "SoccerGame",
            "_id": "SoccerGame_490555",
            "away_score": null,
            "away_team": {
                "_entity_type": "SoccerTeam",
                "_id": "SoccerTeam_86",
                "espn_id": 86,
                "id": "SoccerTeam_86",
                "logo_url": "http://a.espncdn.com/combiner/i?img=/i/teamlogos/soccer/500/86.png&h=500",
                "team_name": "Real Madrid"
            },
            "competition": "Spanish Primera División",
            "game_id": "490555",
            "home_score": null,
            "home_team": {
                "_entity_type": "SoccerTeam",
                "_id": null,
                "team_name": "Leganes"
            },
            "link": "http://m.espn.go.com/soccer/gamecast?gameId=490555&lang=EN&wjb=",
            "start_datetime": {
                "countdown": 86970,
                "datetime": "2018-02-21T17:45:00+0000",
                "timestamp": 1519235100
            },
            "status": "FUTURE",
            "timestamp": 1519235100
        }
    ]
}

Optional: Pull the data

You can use fetch endpoint to request the data currently available for your HQL query. Hooks will return the latest data available for HQL query. The result may be empty if we currently don’t have any data available for your query.

To pull the data for “All Manchester City soccer games” you can use.

SELECT * FROM SoccerGames 
WHERE away_team.team_name = 'Manchester City'
OR home_team.team_name = 'Manchester City'

This query will return all soccer games planned for yesterday, today and tomorrow:

{
    "matches_count": 1,
    "results": [
        {
            "_entity_type": "SoccerGame",
            "_id": "SoccerGame_506575",
            "away_score": 0,
            "away_team": {
                "_entity_type": "SoccerTeam",
                "_id": "SoccerTeam_382",
                "espn_id": 382,
                "id": "SoccerTeam_382",
                "logo_url": "http://a.espncdn.com/combiner/i?img=/i/teamlogos/soccer/500/382.png&h=500",
                "team_name": "Manchester City"
            },
            "competition": "English FA Cup",
            "game_id": "506575",
            "home_score": 1,
            "home_team": {
                "_entity_type": "SoccerTeam",
                "_id": "SoccerTeam_350",
                "espn_id": 350,
                "id": "SoccerTeam_350",
                "logo_url": "http://a.espncdn.com/combiner/i?img=/i/teamlogos/soccer/500/350.png&h=500",
                "team_name": "Wigan Athletic"
            },
            "link": "http://m.espn.go.com/soccer/gamecast?gameId=506575&lang=EN&wjb=",
            "start_datetime": null,
            "status": "FINAL"
        }
    ]
}

Step 2: Create subscription

To create a subscription you just need to send an HQL query and a title of your choice to the subscriptions endpoint:

curl -H "Content-type: application/json" -d '{
	"query": "SELECT * FROM SoccerGames WHERE away_team.team_name = \'Manchester City\' or home_team.team_name = \'Manchester City\' start_datetime.countdown = 3600"
}' 'http://api.hooksdata.io/v1/subscriptions'

Hooks will then create a subscription on our servers and call your webhook once new data is available for your query.

Examples

Using HQL you can customize what data you want to select from a datasource and also filter the output using a WHERE clause. The following examples show how you can use HQL to choose just the data you need:

Real Madrid is going to play a game in 1 hour.

SELECT * FROM SoccerGames 
WHERE status = 'FUTURE' 
AND (away_team.team_name = 'Real Madrid' OR home_team.team_name='Real Madrid')
AND start_datetime.countdown >= 3600

Barcelona won Real Madrid with a score 2:1.

SELECT * FROM SoccerGames 
WHERE status = 'FINISHED'
AND away_team.team_name = 'Real Madrid'
AND home_team.team_name = 'Barcelona'
AND home_score = 2
AND away_score = 1

Soccer game ended with a score 2:1 or 1:2.

SELECT * FROM SoccerGames 
WHERE status = 'FINISHED'  
AND (away_score = 2
AND home_score = 1) OR (home_score = 2
AND away_score = 1)