TotalCorner API Specification v1.0

Overview

TotalCorner has been running for few years. To better serve our customers, we developed this set of API for people to make best use of data.

The API is only available to VIP members.

Endpoints

All endpoints start with https://api.totalcorner.com/v1/

Request

For security reason the server only accepts HTTPS request. HTTP is not supported.
- Token

You can generate/update a TOKEN at user center page. You have to append it to the URL as query parameter named 'token' for each request.

- Rate Limiting

To avoid abuse of API and to balance the maintenance cost, currently we allow maximum 30 requests per minute. You can check the following values in response header for details.

  • X-Rate-Limit-Limit: The maximum number of requests that the consumer is permitted to make in rate limit window.
  • X-Rate-Limit-Remaining: The number of requests remaining in the current rate limit window.
  • X-Rate-Limit-Reset: The time at which the current rate limit window resets in seconds.

Response

Response will be in JSON format. The response JSON object consists of 4 keys: success, error, pagination, data.

The language of team/league name and timezone will be set according to user's profile.

//success response
{
    "success": 1,
    "pagination": {
        "current":3,
        "prev":true,
        "next":true,
        "per_page":30,
        "pages":6
    },
    "data": [
        ... 
    ]
}

//error response
{
    "success": 0,
    "error": {
        "code": "TOKEN_ERROR",
        "message": "token not found",
    }
}

Endpoints Details

Today List

Get list of today matches. The time period is from 00:00 (London Time) to the next day 02:00 (London time).

GET /match/today
Param NameRequired? DefaultDescription
typeNoinplaySpecify the type of matches. Possible values are inplay, upcoming, ended.
pageNo1Pagination reference
columnsNo

By default the API returns the data of FT/HT goal, corner, yellow card, red card. To get more data, you have to pass list of columns as query parameter, combined by comma.The format would be "column_1,column_2,column_3...".

All the possible columns are
  • events
  • odds
  • asian
  • cornerLine
  • cornerLineHalf
  • goalLine
  • goalLineHalf
  • asianCorner
  • attacks
  • dangerousAttacks
  • shotOn
  • shotOff
  • possession
  • userRemarks

Sample request URL: https://api.totalcorner.com/v1/match/today?token=YOUR_TOKEN&type=inplay&columns=events,odds,asian,cornerLine,goalLine,asianCorner,attacks

{
  "success": 1,
  "pagination": {
    "current": 1,
    "prev": false,
    "next": false,
    "per_page": 30,
    "pages": 1
  },
  "data": [
    {
    /*** default columns ***/
      "id": "61421382",
      "h": "Hue",
      "h_id": "13367",
      "a": "Dak Lak",
      "a_id": "10523",
      "l": "World Club Friendlies",
      "l_id": "167",
      "start": "2017-01-13 08:00:00",
      "status": "79",
      "hc": "6",	// home corner
      "ac": "1",	// away corner
      "hg": "1",	// home goal
      "ag": "1",	// away goal
      "hrc": "0",	// home red card
      "arc": "0",	// away red card
      "hyc": "1",	// home yellow card
      "ayc": "1", 	// away yellow card
      "hf_hc": "4",	// half-time home corner
      "hf_ac": "0",	// half-time away corner
      "hf_hg": "0",	// half-time home goal
      "hf_ag": "1",	// half-time away goal
      "ish":	"1" //flag for whether is second-half
      "hp":	"5" //home league position
      "ap":	"8" //away league position
      
     /*** belowings are extra columns, need to be specified through query parameters ***/
      "events": [	// events of goal, corner, red card
        {
          "tp": "c",	// type: 'c' for corner, 'g' for goal, 'rc' for red card
          "h": "a",	// home or away: 'h' for home, 'a' for away
          "t": "74"	// time of the event
        },
        {
          "tp": "g",
          "h": "h",
          "t": "70"
        },
        {
          "tp": "c",
          "h": "h",
          "t": "65"
        },
        {
          "tp": "c",
          "h": "h",
          "t": "53"
        },
        {
          "tp": "c",
          "h": "h",
          "t": "37"
        },
        {
          "tp": "c",
          "h": "h",
          "t": "35"
        },
        {
          "tp": "c",
          "h": "h",
          "t": "26"
        },
        {
          "tp": "c",
          "h": "h",
          "t": "23"
        },
        {
          "tp": "g",
          "h": "a",
          "t": "20"
        }
      ],
      "p_odds": [	// pre-match odds, latest
        "2.15",
        "3.75",
        "2.75"
      ],
      "po_odds": [	// pre-match odds, opening
        "1.95",
        "3.40",
        "4.00"
      ],
      "i_odds": [	// inplay odds
        "5.00",
        "1.333",
        "9.00"
      ],
      "p_asian": [	// asian handicap
        "0.0"
      ],
      "i_asian": [
        "0.0"
      ],
      "p_corner": [	// corner line
        ""
      ],
      "i_corner": [
        ""
      ],
      "p_goal": [	// goal line
        "3.0"
      ],
      "i_goal": [
        "2.5"
      ],
      "asian_corner": [	// asian handicap for corner
        ""
      ],
      "attacks": [
        "24",
        "30"
      ],
       "attacks_h": [	// attacks at half-time
        "15",
        "18"
      ],
      "shot_on": [
        "3",
        "5"
      ],
      "shot_on_h": [
        "1",
        "2"
      ],
      "shot_off": [
        "4",
        "0"
      ],
      "shot_off_h": [
        "2",
        "0"
      ],
      "possess": [
        "51",
        "49"
      ],
      "possess_h": [
        "50",
        "50"
      ],
      "remarks": "",	// user notes
      "like": "",	// user favorite
          },
    ...
  ]
}

Match Schedule

Get list of matches given date.

GET /match/schedule
Param NameRequired? DefaultDescription
dateNoTODAYformat YYYYMMDD, eg: 20170101
pageNo1Pagination reference
columnsNo Same as '/match/today'

Sample request URL: https://api.totalcorner.com/v1/match/schedule?token=YOUR_TOKEN&date=20170101&columns=events,odds,asian,cornerLine,goalLine,asianCorner,attacks

/*** similar to response of '/match/today' ***/

Match View

Get match info given match_id.

GET /match/view/{match_id}
Param NameRequired? DefaultDescription
columnsNo Same as '/match/today'

Sample request URL: https://api.totalcorner.com/v1/match/view/61421382?token=YOUR_TOKEN&columns=events,odds,asian,cornerLine,goalLine,asianCorner,attacks

/*** similar to response of '/match/today' ***/

Match Odds

Get the history of odds changes given match_id.

GET /match/odds/{match_id}
Param NameRequired? DefaultDescription
columnsNo

By default the API returns the data of FT/HT goal, corner, yellow card, red card. To get more data, you have to pass list of columns as query parameter, combined by comma.The format would be "column_1,column_2,column_3...".

All the possible columns are
  • asianList
  • goalList
  • cornerList
  • oddsList
  • asianHalfList
  • goalHalfList
  • cornerHalfList
  • oddsHalfList

Sample request URL: https://api.totalcorner.com/v1/match/odds/61421382?token=YOUR_TOKEN&columns=asianList,goalList,cornerList,oddsList,asianHalfList,goalHalfList

{
  "success": 1,
  "data": [
    {
    /*** default columns ***/
      "id": "61416577",
      "h": "Brisbane Wolves",
      "h_id": "11600",
      "a": "Moreton Bay United",
      "a_id": "10118",
      "l": "Australia Friendlies",
      "l_id": "430",
      "start": "2017-01-13 10:30:00",
      "status": "26",
      "hc": "0",
      "ac": "0",
      "hg": "0",
      "ag": "1",
      "hrc": "0",
      "arc": "0",
      "hyc": "0",
      "ayc": "0",
      "hf_hc": "0",
      "hf_ac": "0",
      "hf_hg": "0",
      "hf_ag": "1",

    /*** belowings are extra columns, need to be specified through query parameters ***/
      "asian_list": [	// list of asian handicap
        [
          "26",	// match status
          "+1.5",	// handicap
          "1.975",	// home line
          "1.825",	// away line
          "2017-01-13 11:00:37",	// time
          "0",	// hoem goal
          "1"	// away goal
        ],
        ...
      ],
      "goal_list": [
        [
          "26",
          "3.5,4.0",
          "1.95",
          "1.85",
          "2017-01-13 11:00:37",
          "0",
          "1"
        ],
        ...
      ],
      "corner_list": [
        [
          "25",
          "6.0",
          "1.95",
          "1.85",
          "2017-01-13 11:00:28",
          "0",
          "0"
        ],
        ...
      ],
      "odds_list": [
        [
          "26",
          "21.00",
          "11.00",
          "1.05",
          "2017-01-13 11:00:37",
          "0",
          "1"
        ],
        ...
      ],
      "asian_half_list": [
        ...
      ],
      "goal_half_list": [
        ...
      ],
      "corner_half_list": [
        ...
      ],
      "odds_half_list": [
        ...
      ]
    }
  ]
}

League Table

Get league stats of scoretable, corner and cards.

GET /league/table/{league_id}
Param NameRequired? DefaultDescription
typeNotableSpecify the type of tables. Possible values are table, corner, card.

Sample request URL: https://api.totalcorner.com/v1/league/table/1?token=YOUR_TOKEN&type=corner

/*** league corner stats response ***/
{
  "success": 1,
  "data": {
    "league_id": "1",
    "league_name": "England Premier League",
    "season": "16/17",
    "country": "England",
    "table_items": [
      {
        "team": "Man City",
        "team_id": "9",
        "played": "20",
        "position": "1",
        "get": "147",
        "lost": "70",
        "average_get": "7.35",
        "average_lost": "3.50",
        "half_get": "76",
        "half_lost": "25",
        "half_average_get": "3.80",
        "half_average_lost": "1.25"
      },
	  ...     
    ]
  }
}

League Schedule

Get list of matches given league_id.

GET /league/schedule/{league_id}
Param NameRequired? DefaultDescription
pageNo1Pagination reference
columnsNo Same as '/match/today'

Sample request URL: https://api.totalcorner.com/v1/league/schedule/1?token=YOUR_TOKEN&columns=events,odds,asian,cornerLine,goalLine,asianCorner,attacks

{
  "success": 1,
  "pagination": {
    "current": 1,
    "prev": false,
    "next": true,
    "per_page": 30,
    "pages": 34
  },
  "data": {
    "league": {
      "league_id": "1",
      "name": "England Premier League",
      "country": "England"
    },
    "matches": [
      {
       /*** default columns ***/
        "id": "61187038",
        "h": "Chelsea",
        "h_id": "16",
        "a": "Hull",
        "a_id": "12",
        "l": "England Premier League",
        "l_id": "1",
        "start": "2017-01-22 16:30:00",
        "status": null,
        "hc": "0",
        "ac": "0",
        "hg": "0",
        "ag": "0",
        "hrc": "0",
        "arc": "0",
        "hyc": "0",
        "ayc": "0",
        "hf_hc": "0",
        "hf_ac": "0",
        "hf_hg": "0",
        "hf_ag": "0",

         /*** belowings are extra columns, need to be specified through query parameters ***/
        "events": null,
        "p_odds": [
          "1.16",
          "7.50",
          "13.00"
        ],
        "i_odds": [
          null,
          null,
          null
        ],
        "p_asian": [
          "-2.0"
        ],
        "i_asian": [
          ""
        ],
        "p_corner": [
          ""
        ],
        "i_corner": [
          ""
        ],
        "p_goal": [
          "3.0"
        ],
        "i_goal": [
          ""
        ],
        "asian_corner": [
          ""
        ],
        "attacks": [
          "0",
          "0"
        ],
        "shot_on": [
          "0",
          "0"
        ],
        "shot_off": [
          "0",
          "0"
        ],
        "possess": [
          "0",
          "0"
        ],
        "remarks": "",
        "like": "",
              },
     ...
    ]
  }
}

Reference

error

error codeDescription
TOKEN_ERRORToken is missing or incorrect.
PARAM_ERRORParameters is missing or invalid.
NO_PERMISSIONNo permission to access. Not a VIP member.
TOO_MANY_REQUESTExceed the request limit at current time window. Wait for the next time window.
INTERNAL_SERVER_ERRORExceptions raised by the server.
UNDER_MAINTENANCEServer under maintenance.

Pagination

Pagination is usually used when retrieve list of matches.

ElementDescription
currentCurrent page
prevWhether there is previous page
nextWhether there is next page
per_pageNumber of result per page. Currently it's set to 30 and not configurable
pagesTotal number of pages

To be added.

2017-07-24

  • Add half-time stats of attacks,dangerous attacks, shots and possessions.

2017-06-02

  • Add league position and pre-match opening odds.

2017-05-13

  • Add Half-time goal line and Half-time corner line

2017-04-28

  • Add flag to indicate whether is second half

2017-01-10

  • Add columns to query parameter

2017-01-05

  • First draft