Overview Validation¶

These resources are used by Match Resources resources to cross-reference static data related to high-level match information. (Personnel resources also cross-reference Country resource representations.)

Confederations¶

GET /v1/confederations/(int: ID)¶

Returns the names of the football confederations in the world. If ID is passed, return data for the confederation the ID corresponds to.

If query parameters are passed, it returns the record that matches the specified filters.

Warning

This resource cannot be paginated. Any requests with records or page parameters will return a 400 BAD REQUEST error.

Query and Response Parameters:

Field	Type	Description
name	string	Acronym of football confederation.

Link Parameters:

Field	URL Description
countries	Countries resource representation.

Example:

GET /v1/confederations/13 HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Wed, 23 Jul 2014 04:51:34 GMT
Connection: close
Content-Type: application/json
Content-Length: 591

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {},
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {},
  "result": [
    {
      "id": 13,
      "link": {
        "countries": "/v1/countries?confederation=13"
      },
      "name": "CONMEBOL",
      "uri": "/v1/confederations/13"
    }
  ]
}

OPTIONS /v1/confederations¶: Returns documentation of the confederations resource.

Countries¶

GET /v1/countries/(ID)¶

Returns the names of the “FIFA countries” – the FIFA-affiliated football associations in the world.

If ID is passed, return data for the country the ID corresponds to.

If query parameters are passed, it returns the records that match the specified filters.

Query and Response Parameters:

Field	Type	Description
name	string	Popular name of FIFA-affiliated football association.
confederation	integer	The unique ID of the football confederation the country belongs to.

Link Parameters:

Field	URL Description
confederation	Confederations resource representation.
managers	Managers resource representations of same country.
players	Players resource representation of same country.
referees	Referees resource representation of same country.
venues	Match Venues resource representation of same country.
teams	Teams resource representation of same country.

Example:

GET /v1/countries/6aa38b7b9246427ca2888a804102c823 HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Wed, 23 Jul 2014 04:58:45 GMT
Connection: close
Content-Type: application/json
Content-Length: 1360

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {},
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {
    "first": "/v1/countries/6aa38b7b9246427ca2888a804102c823?records=10&page=1",
    "last": "/v1/countries/6aa38b7b9246427ca2888a804102c823?records=10&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 1
  },
  "result": [
    {
      "confederation": 13,
      "id": "6aa38b7b9246427ca2888a804102c823",
      "link": {
        "confederation": "/v1/confederations/13",
        "managers": "/v1/personnel/managers?country=6aa38b7b9246427ca2888a804102c823",
        "players": "/v1/personnel/players?country=6aa38b7b9246427ca2888a804102c823",
        "referees": "/v1/personnel/referees?country=6aa38b7b9246427ca2888a804102c823",
        "teams": "/v1/teams?country=6aa38b7b9246427ca2888a804102c823",
        "venues": "/v1/venues?country=6aa38b7b9246427ca2888a804102c823"
      },
      "name": "Chile",
      "uri": "/v1/countries/6aa38b7b9246427ca2888a804102c823"
    }
  ]
}

OPTIONS /v1/countries¶: Returns documentation of the countries resource.

Competitions¶

GET /v1/competitions/(ID)¶

Returns the names of the football competitions in the database. If ID is passed, return the competition record the ID corresponds to.

If query parameters are passed, it returns the records that match the specified filters.

Warning

This resource cannot be paginated. Any requests with records or page parameters will return a 400 BAD REQUEST error.

Query and Response Parameters:

Field	Type	Description
name	string	The name of the football competition.
level	integer	Competition level in organization’s hierarchy.

Example:

GET /v1/competitions HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Wed, 23 Jul 2014 05:02:40 GMT
Connection: close
Content-Type: application/json
Content-Length: 615

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {},
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {},
  "result": [
    {
      "id": "3f062dd43b8c4f4895bdffc3f5c00467",
      "level": 1,
      "link": {},
      "name": "FIFA World Cup",
      "uri": "/v1/competitions/3f062dd43b8c4f4895bdffc3f5c00467"
    }
  ]
}

OPTIONS /v1/competitions¶: Returns documentation of the competitions resource.

Domestic Competitions¶

GET /v1/domestic_competitions/(ID)¶

Returns the names of the domestic football competitions in the database. By “domestic” we mean a competition organized by a national football association.

If ID is passed, return the competition record the ID corresponds to.

If query parameters are passed, it returns the records that match the specified filters.

Warning

This resource cannot be paginated. Any requests with records or page parameters will return a 400 BAD REQUEST error.

Query and Response Parameters:

Field	Type	Description
competition	uuid	The unique ID of the football competition.
country	uuid	The unique ID of the national association to which the competition belongs.

International Competitions¶

GET /v1/intl_competitions/(ID)¶

Returns the names of the international football competitions in the database. These are competitions organized by a football confederation, such as UEFA or FIFA.

If ID is passed, return the competition record the ID corresponds to.

If query parameters are passed, it returns the records that match the specified filters.

Warning

This resource cannot be paginated. Any requests with records or page parameters will return a 400 BAD REQUEST error.

Query and Response Parameters:

Field	Type	Description
competition	uuid	The unique ID of the football competition.
confederation	integer	The unique ID of the football confederation to which the competition belongs.

Link Parameters:

Field	URL Description
confederation	Confederations resource representation.

Example:

GET /v1/intl_competitions/7480313027e4457da45dd85d23269ea7 HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Wed, 23 Jul 2014 05:21:36 GMT
Connection: close
Content-Type: application/json
Content-Length: 710

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {},
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {},
  "result": [
    {
      "competition": "3f062dd43b8c4f4895bdffc3f5c00467",
      "confederation": 16,
      "id": "7480313027e4457da45dd85d23269ea7",
      "link": {
        "confederation": "/v1/confederations/16"
      },
      "uri": "/v1/intl_competitions/7480313027e4457da45dd85d23269ea7"
    }
  ]
}

Competition Phases¶

GET /v1/phases/(int: ID)¶

Returns the phases of a football competition. A description of the phases is presented below.

Competition Phase	Description	Examples
League	A long-term competition in which teams play each other (typically home and away) over multiple matchdays.	Football League, Major League Soccer regular season, Brasileirão
Group	A short-term competition similar to a league format, but with a reduced number of teams and matchdays.	UEFA Champions League group stage, FIFA World Cup group stage
Knockout	A competition played over successive rounds, in which each fixture is over played over single or multiple matches.	FA Cup, League Cup, MLS Cup Playoffs, FIFA World Cup knockout stage

If ID is passed, return data for the competition phase the ID corresponds to.

If query parameters are passed, it returns the record that matches the specified filters.

Warning

This resource cannot be paginated. Any requests with records or page parameters will return a 400 BAD REQUEST error.

Query and Response Parameters:

Field	Type	Description
name	string	Description of competition phase.

Example:

GET /v1/phases HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Wed, 23 Jul 2014 05:33:56 GMT
Connection: close
Content-Type: application/json
Content-Length: 723

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {},
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {},
  "result": [
    {
      "id": 1,
      "link": {},
      "name": "League",
      "uri": "/v1/phases/1"
    },
    {
      "id": 2,
      "link": {},
      "name": "Group",
      "uri": "/v1/phases/2"
    },
    {
      "id": 3,
      "link": {},
      "name": "Knockout",
      "uri": "/v1/phases/3"
    }
  ]
}

Group Rounds¶

GET /v1/grouprounds/(int: ID)¶

Returns the names of the rounds during the group phase of a competition.

If ID is passed, return data for the group phase round the ID corresponds to.

If query parameters are passed, it returns the record that matches the specified filters.

Warning

This resource cannot be paginated. Any requests with records or page parameters will return a 400 BAD REQUEST error.

Query and Response Parameters:

Field	Type	Description
name	string	Description of group stage round.

Example:

GET /v1/grouprounds/1 HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Wed, 23 Jul 2014 05:45:28 GMT
Connection: close
Content-Type: application/json
Content-Length: 528

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {},
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {},
  "result": [
    {
      "id": 1,
      "link": {},
      "name": "Group Stage",
      "uri": "/v1/grouprounds/1"
    }
  ]
}

Knockout Rounds¶

GET /v1/knockoutrounds/(int: ID)¶

Returns the names of the rounds during the knockout phase of a competition.

If ID is passed, return data for the knockout phase round the ID corresponds to.

If query parameters are passed, it returns the record that matches the specified filters.

Warning

This resource cannot be paginated. Any requests with records or page parameters will return a 400 BAD REQUEST error.

Query and Response Parameters:

Field	Type	Description
name	string	Description of knockout stage round.

Example:

GET /v1/knockoutrounds/17 HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Wed, 23 Jul 2014 05:48:33 GMT
Connection: close
Content-Type: application/json
Content-Length: 539

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {},
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {},
  "result": [
    {
      "id": 17,
      "link": {},
      "name": "Round of 16 (1/8)",
      "uri": "/v1/knockoutrounds/17"
    }
  ]
}

Weather¶

GET /v1/weather/(int: ID)¶

Returns the descriptions of specific weather conditions. The descriptions are terms used by the US National Weather Service.

If ID is passed, return the weather condition record the ID corresponds to.

If query parameters are passed, it returns the records that match the specified filters.

Warning

This resource cannot be paginated. Any requests with records or page parameters will return a 400 BAD REQUEST error.

Query and Response Parameters:

Field	Type	Description
desc	string	Description of the weather condition, using terms from US NOAA National Weather Service.

Example:

GET /v1/weather/15 HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Thu, 24 Jul 2014 04:21:49 GMT
Connection: close
Content-Type: application/json
Content-Length: 528

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {},
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {},
  "result": [
    {
      "desc": "Partly Cloudy",
      "id": 15,
      "link": {},
      "uri": "/v1/weather/15"
    }
  ]
}

OPTIONS /v1/weather¶: Returns documentation of the weather condition resource.

Playing Surfaces¶

GET /v1/surfaces/(int: ID)¶

Returns the descriptions of playing surfaces.

If ID is passed, return the surface record the ID corresponds to.

If query parameters are passed, it returns the records that match the specified filters.

Warning

This resource cannot be paginated. Any requests with records or page parameters will return a 400 BAD REQUEST error.

Query and Response Parameters:

Field	Type	Description
name	string	The type of field surface.

Example:

GET /v1/surfaces/5 HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Thu, 24 Jul 2014 04:24:53 GMT
Connection: close
Content-Type: application/json
Content-Length: 531

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {},
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {},
  "result": [
    {
      "desc": "Desso GrassMaster",
      "id": 5,
      "link": {},
      "uri": "/v1/surfaces/5"
    }
  ]
}

OPTIONS /v1/surfaces¶: Returns documentation of the playing surface resource.

Seasons¶

GET /v1/seasons/(int: ID)¶

Returns the competition season year(s).

If ID is passed, return the season year(s) the ID corresponds to.

If query parameters are passed, it returns the records that match the specified filters.

Warning

This resource cannot be paginated. Any requests with records or page parameters will return a 400 BAD REQUEST error.

Query and Response Parameters:

Field	Type	Description
name	string	Season year(s).

Example:

GET /v1/seasons/100 HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Thu, 24 Jul 2014 04:27:12 GMT
Connection: close
Content-Type: application/json
Content-Length: 524

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {},
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {},
  "result": [
    {
      "id": 100,
      "link": {},
      "name": "2013-14",
      "uri": "/v1/seasons/100"
    }
  ]
}

OPTIONS /v1/seasons¶: Returns documentation of the seasons resource.

Teams¶

GET /v1/teams/(ID)¶

Returns the name of the club team.

If ID is passed, return the team the ID corresponds to.

If query parameters are passed, it returns the records that match the specified filters.

Query and Response Parameters:

Field	Type	Description
name	string	The club team name.
country	uuid	The unique ID of the country where the club team resides.

Link Parameters:

Field	URL Description
country	Countries resource representation.

OPTIONS /v1/teams¶: Returns documentation of the team resource.

Time Zones¶

GET /v1/timezones/(int: ID)¶

Returns data on the time zone regions throughout the world.

If ID is passed, return the match venue the ID corresponds to.

If query parameters are passed, it returns the records that match the specified filters.

Query and Response Parameters:

Field	Type	Description
name	string	The name of the time zone region.
confederation	integer	The unique ID of the football confederation in which the time zone region resides.
offset	float	The time offset of the time zone region from UTC, in decimal hours.

Link Parameters:

Field	URL Description
confederation	Confederations resource representation.

Example:

GET /v1/timezones/1009 HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Thu, 24 Jul 2014 04:51:38 GMT
Connection: close
Content-Type: application/json
Content-Length: 886

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {},
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {
    "first": "/v1/timezones/1009?records=10&page=1",
    "last": "/v1/timezones/1009?records=10&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 1
  },
  "result": [
    {
      "confederation": 13,
      "id": 1009,
      "link": {
        "confederation": "/v1/confederations/13"
      },
      "name": "America/Argentina/Buenos_Aires",
      "offset": -3.0,
      "uri": "/v1/timezones/1009"
    }
  ]
}

OPTIONS /v1/timezones¶: Returns documentation of the time zone resource.

Match Venues¶

GET /v1/venues/(ID)¶

Returns data on the match venue where a football match is held.

If ID is passed, return the match venue the ID corresponds to.

If query parameters are passed, it returns the records that match the specified filters.

Query and Response Parameters:

Field	Type	Description
name	string	The name of the match venue.
team	uuid	The unique ID of the team who plays its home matches at the venue. If there are multiple home teams, this field is set to null.
city	string	The name of the city where the venue resides.
country	uuid	The unique ID of the country where the venue resides.
timezone	integer	The unique ID of the venue’s time zone region.
latitude	float	The latitude of the venue in decimal degrees.
longitude	float	The longitude of the venue in decimal degrees.
altitude	float	The altitude of the venue in meters.
length	integer	The length of the venue playing surface in meters.
width	integer	The width of the venue playing surface in meters.
capacity	integer	The total capacity of the venue.
seated	integer	The total number of seats at the venue.
surface	integer	The unique ID of the playing surface type that the venue uses for matches.

Link Parameters:

Field	URL Description
country	Countries resource representation.

Example:

GET /v1/venues?city=Brasília HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Thu, 24 Jul 2014 04:29:37 GMT
Connection: close
Content-Type: application/json
Content-Length: 1275

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {},
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {
    "first": "/v1/venues?city=Bras%C3%ADlia&page=1&records=10",
    "last": "/v1/venues?city=Bras%C3%ADlia&page=1&records=10",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 1
  },
  "result": [
    {
      "altitude": 1120.0,
      "capacity": 70042,
      "city": "Bras\u00edlia",
      "country": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "id": "ae56ae8cf8244427bf748ae8ab79fb1b",
      "latitude": -15.7835,
      "length": 105,
      "link": {
        "country": "/v1/countries/70ce7b6218a24e1d94c21ed8b5cd070c"
      },
      "longitude": -47.899164,
      "name": "Est\u00e1dio Nacional Man\u00e9 Garrincha",
      "seated": 70042,
      "surface": 1,
      "team": null,
      "timezone": 1058,
      "uri": "/v1/venues/ae56ae8cf8244427bf748ae8ab79fb1b",
      "width": 68
    }
  ]
}

OPTIONS /v1/venues¶: Returns documentation of the match venue resource.