JSON Data

This reference page documents the response format that our football API endpoints return.

When you call our football API, you will get a JSON response always. An exception to this rule is the countries flags api endpoint where you will get an image as a response.

With the JSON format, each response carries two elements. The first is a success flag that tells you whether your request went through or not. When the call succeeds, a data element appears alongside it and holds the payload you are after. When something goes wrong, an error element shows up in place of data. More details on that are covered in our common error reference page. A JSON response example is shown below.

{
    "success": true,
    "data": {
        "teams": [
            {
                "team_id": 7,
                "matches": [
                    {
                        "match_id": 683244,
                        "events": [
                            {
                                "event_type": "GOAL",
                                "minute": 41
                            },
                            {
                                "event_type": "GOAL",
                                "minute": 43
                            },
                            {
                                "event_type": "GOAL",
                                "minute": 67
                            },
                            {
                                "event_type": "GOAL",
                                "minute": 90
                            }
                        ]
                    },
                    {
                        "match_id": 682374,
                        "events": [
                            {
                                "event_type": "GOAL",
                                "minute": 15
                            },
                            {
                                "event_type": "GOAL",
                                "minute": 21
                            },
                            {
                                "event_type": "GOAL",
                                "minute": 50
                            },
                            {
                                "event_type": "GOAL",
                                "minute": 57
                            },
                            {
                                "event_type": "GOAL",
                                "minute": 61
                            },
                            {
                                "event_type": "GOAL",
                                "minute": 90
                            }
                        ]
                    }
                ]
            },
            {
                "team_id": 19,
                "matches": [
                    {
                        "match_id": 683454,
                        "events": [
                            {
                                "event_type": "GOAL",
                                "minute": 19
                            },
                            {
                                "event_type": "GOAL",
                                "minute": 56
                            },
                            {
                                "event_type": "GOAL",
                                "minute": 90
                            }
                        ]
                    },
                    {
                        "match_id": 681911,
                        "events": [
                            {
                                "event_type": "GOAL",
                                "minute": 37
                            },
                            {
                                "event_type": "GOAL",
                                "minute": 50
                            },
                            {
                                "event_type": "GOAL",
                                "minute": 87
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Here you see an example with an error message instead.

{
    "success": false,
    "error": "This API key and secret do not have access to our data enabled"
}