API Flexibility & Relationships

API Flexibility & Relationships

The flexibility of our API is in the part where you build your own responses by adding include parameters to your request. On every endpoint you can find information on what data can be included and how deep you can add includes. To best describe how to use includes and what the include limit means, we will give an explanation based on some example calls.

Getting Livescores

So, imagine you have an application that needs to show our fast livescores. To get all games currently played you will call the "Livescores In-play" endpoint like this:

https://cricket.sportmonks.com/api/v2.0/livescores?api_token=__TOKEN__

This will result in a collection of all games that are currently being played, and that are covered by your subscription.

Adding Team information

Usefull information for every game is home and away team information. How else would you know between which 2 teams the game is being played? Here we start with the interesting part, including team information.

https://cricket.sportmonks.com/api/v2.0/livescores?api_token=__TOKEN__&include=localteam,visitorteam
"data": {
    "resource": "fixtures",
    "id": 9635,
    // ....
    "localteam": {
        "resource": "teams",
        "name": "Melbourne Stars",
        "code": "MS",
        "image_path": "https://cdn.sportmonks.com/images/cricket/teams/19/51.png",
        "country_id": 98,
        "national_team": false,
        "updated_at": "2018-11-29T11:47:20.000000Z"
    },
    "visitorteam": {
        "resource": "teams",
        "name": "Melbourne Renegades",
        "code": "MR",
        "image_path": "https://cdn.sportmonks.com/images/cricket/teams/18/50.png",
        "country_id": 98,
        "national_team": false,
        "updated_at": "2018-11-29T11:47:20.000000Z"
    }
}

Note that we have extended our request with "&include=localteam,visitorteam". This results in information about the home and away team. You will retrieve a full team object related to the response whch includes the name, logo url and much more information.

Adding Runs, Balls and Scoreboards

What is a game without the progression? Important information for your application to show could be bowling and batting information, lineup or runs.

https://cricket.sportmonks.com/api/v2.0/livescores?api_token=__TOKEN__&include=localteam,visitorteam,lineup,runs,bowlings,battings
"data": {
    "resource": "fixtures",
    "id": 9635,
    // ....
    "runs": [
        {
            "resource": "runs",
            "id": 18032,
            "fixture_id": 9635,
            "team_id": 50,
            "inning": 1,
            "score": 145,
            "wickets": 5,
            "overs": 20,
            "pp1": "1-6",
            "pp2": null,
            "pp3": null,
            "updated_at": "2019-02-17T05:27:24.000000Z",
            "team": {
                "resource": "teams",
                "name": "Melbourne Renegades",
                "code": "MR",
                "image_path": "https://cdn.sportmonks.com/images/cricket/teams/18/50.png",
                "country_id": 98,
                "national_team": false,
                "updated_at": "2018-11-29T11:47:20.000000Z"
            }
        },
        {
            "resource": "runs",
            "id": 18041,
            "fixture_id": 9635,
            "team_id": 51,
            "inning": 2,
            "score": 132,
            "wickets": 7,
            "overs": 20,
            "pp1": "1-6",
            "pp2": null,
            "pp3": null,
            "updated_at": "2019-02-17T07:10:15.000000Z",
            "team": {
                "resource": "teams",
                "name": "Melbourne Stars",
                "code": "MS",
                "image_path": "https://cdn.sportmonks.com/images/cricket/teams/19/51.png",
                "country_id": 98,
                "national_team": false,
                "updated_at": "2018-11-29T11:47:20.000000Z"
            }
        }
    ]
}

We have extended our request url with use full information about the scores and lineups now. Pretty cool right, but hey, to what players are the scoeboard even related to? With the current URL we have no clue since it only shows the player_id, not the actual name.

Adding nested includes

Luckely the flexibility of the API goes a step further with nested includes. Nested includes are basically relations on relations for the base endpoint. What?! relations of relations..... Now, for most apps this is already more then enough info to show, but in this case we don't want the common name but the fullname we can enricht the event with actual player information showing all details of the player who was responsible for the event.

https://cricket.sportmonks.com/api/v2.0/livescores/now?api_token=__TOKEN__&include=balls, localteam,visitorteam,lineup.player,runs.team,bowlings.team,battings.team

Note we have added the .player to the lineup include? or teams to runs, battings and bowlings?

{tip} You can add as many nested includes as described in the documentation section of the endpoint it self.

Include limit

The number of nested includes can be found on the documentation section of the endpoint. To make it more clear we will give you some examples. Imagine we have an include limit of 2.

https://cricket.sportmonks.com/api/v2.0/livescores?api_token=__TOKEN__&include=lineup.player

This will return all data requested.

"lineup": [
    {
       "resource": "lineups",        
       "id": 199,
        "country_id": 98,
        "firstname": "Marcus",
        "lastname": "Stoinis",
        "fullname": "Marcus Stoinis",
        "image_path": "https://cdn.sportmonks.com/images/cricket/players/7/199.png",
        "dateofbirth": "1989-08-16",
        "gender": "m",
        "position": {
            "id": 1,
            "name": "Batsman"
        },
        "lineup": {
            "team_id": 51,
            "captain": false,
            "wicketkeeper": false
        },
        "updated_at": "2018-11-16T10:12:32.000000Z"
    },
    {
    "resource": "lineups",        
    "id": 456,
        "country_id": 98,
        "firstname": "Ben",
        "lastname": "Dunk",
        "fullname": "Ben Dunk",
        "image_path": "https://cdn.sportmonks.com/images/cricket/players/8/456.png",
        "dateofbirth": "1987-03-11",
        "gender": "m",
        "position": {
            "id": 3,
            "name": "Wicketkeeper"
        },
        "lineup": {
            "team_id": 51,
            "captain": false,
            "wicketkeeper": false
        },
        "updated_at": "2018-11-21T16:14:10.000000Z"
    },
    {
        "id": 454,
        "country_id": 98,
        "firstname": "Peter",
        "lastname": "Handscomb",
        "fullname": "Peter Handscomb",
        "image_path": "https://cdn.sportmonks.com/images/cricket/players/6/454.png",
        "dateofbirth": "1991-04-26",
        "gender": "m",
        "position": {
            "id": 3,
            "name": "Wicketkeeper"
        },
        "lineup": {
            "team_id": 51,
            "captain": false,
            "wicketkeeper": true
        },
        "updated_at": "2018-12-21T07:14:31.000000Z"
    }, // ...
]

Wrapping Up

Based on the above examples you should be able to get a basic understanding of how the SportMonks Cricket API works. You can find all available includes on the documentation section of the endpoint itself. There, you can also find the limit of includes. To use nested includes you must check the documentation of a parent include as well.

Please also read the article about sorting and filtering since this will help you to perform more advanced logic.

Questions?

We're always happy to help with code or other questions you might have! Search our documentation, contact support, or get in touch with our sales team.

This article was last updated on 2019-01-17 15:25:41

{{ loginForm.errors.get('email') }}

{{ loginForm.errors.get('password') }}

Remember me?