ESPN Medals Data

Medals

Code for the gold

  • The ESPN Medals API allows you to interact with medal and event result information from the Summer and Winter Olympic Games.

    This API is currently a version 1 (/v1/) release.

    Availability
    Public Partner Premium Partner ESPN

  • The ESPN Medals API accepts a GET request.

    Users can retrieve medal results for a particular Olympic Games (Winter or Summer) ranked by country, for a specific country, or for a specific athlete.

    The format of an API request is as follows:
    http://api.espn.com/:version/:resource/:method?apikey=:yourkey

    Sample Medals Requests

    Action URI Description
    GET http://api.espn.com/v1/sports/olympics/medals Get medal counts by country for the most recent Olympic Games, ranked by total medals won.
    GET http://api.espn.com/v1/sports/olympics/countries/usa/medals Get medal count for the most recent Olympic Games for the USA.
    GET http://api.espn.com/v1/sports/olympics/countries/usa/medals?enable=competitions Get medal count for the most recent Olympic Games for the USA, with competition details including individual winners and winning score.
    GET http://api.espn.com/v1/sports/olympics/medals?dates=2008&season=summer Get medal counts by country for the 2008 Summer Olympics, ranked by total medals won.
    GET http://api.espn.com/v1/sports/olympics/alpine-skiing/medals?dates=2010&season=winter Get medal counts by country for the 2010 Winter Olympics for alpine skiing competitions.
    GET http://api.espn.com/v1/sports/olympics/athletes/52386/medals?dates=2008&season=summer Get medal performance for an individual athlete in the 2008 Summer Olympics.

    Helper API Calls

    The following "helper" API calls may come in handy when working with the Medals API.

    Action URI Description
    GET http://api.espn.com/v1/sports/olympics/countries Returns an array of countries (including ID, abbreviation, and name) that can be used with the Medals API.
    GET http://api.espn.com/v1/sports/olympics Returns an array of sports (including olympic sport ID and name) for the current Olympic Games that can be used with the Medals API.
    GET http://api.espn.com/v1/sports/olympics?season=winter&dates=2010 Returns an array of sports (including olympic sport ID and name) for a specific Olympic Games that can be used with the Medals API.
  • Quick Navigation

    Resources

    Resource Name Description Availability
    public partner premium
    partner    		 espn
    /sports/olympics Medals for the Olympic Games.
    Back to top

     

    Methods

    Method Description Availability
    public partner premium
    partner    		 espn
    /medals Retrieve an overall ranked list of medal counts ranked by country.
    /countries/:countryAbbrev/medals Retrieve medal information for a specific country.
    /:sportName/medals Retrieve medal information for competitions within a given sport.
    /athletes/:athleteId/medals Retrieve medal information for a particular athlete.
    Back to top

     

    URI Parameters

    In addition to the standard URI parameters, the ESPN Headlines API also supports the following URI parameters:

    Parameter Value & Description Availability
    public partner premium
    partner    		 espn
    season The season of the Olympic Games. Possible values are:
    summer 
    winter 
    dates 4-digit year representation (yyyy) corresponding to a specific instance of the Olympic Games.
    enable Optional flag to enable specific information, with the following options. Accepts a single value or a comma delimited string of values (i.e. enable=a,b,c).
    competitions Competition details including individual winners and winning score.
    flags Collection of country flag images, each containing href, width, and height attributes.
    lang Can be used to return content in the specified language. Supported languages are below. Note: not all content is available in multiple languages and will return in English if no alternative is available.
    en English. Default language.
    es Spanish

    Back to top

     

  • Quick Navigation

    Returned Data

    Requests to the ESPN Medals API return the following data:

    Element Description Availability
    public partner premium
    partner    		 espn
    season Object containing the following properties:
    year The calendar year in which the majority of the sport's season is played.
    type Integer corresponding to the season type (1 = preseason, 2 = regular season, 3 = postseason).
    description String representation of the season type (e.g. "regular" for season type = 2).
    startDate Date for which the season starts for this sport/organizing body.
    endDate Date for which the season ends for this sport/league.
    olympicSeasonId Integer ID corresponding to the specific Olympic Games in ESPN's systems.
    competitors Collection of competitor objects, each containing the following elements:
    type The type of competitor, with possible values of 'country' or 'athlete'
    country Country object if the competitor is of type country. Contains the following properties:
    id - The unique ID for the country in ESPN's systems
    abbreviation- Text abbreviation for the country, e.g. "USA"
    flags - If enabled, returns a collection of country flag images containing href, width, and height attributes.
    medals Object containing the following properties:
    gold - Number of gold medals won.
    silver - Number of silver medals won.
    bronze - Number of bronze medals won.
    overall - Total number of medals won.
    links - Collection of relevant API endpoints and canonical URLs for further event and medals information.
    Back to top

    The following table outlines the data that is returned when the 'competitions' option is enabled. The 'competitions' array appears within the medals.gold, medals.silver, or medals.bronze objects as appropriate.

    Element Description Availability
    public partner premium
    partner    		 espn
    competitions Array of objects each containing the following properties:
    olympicSportId The unique ID of the Olympic sport in ESPN's systems.
    name The name of the competition, e.g. "Women's Balance Beam".
    competitors An array of competitor objects, each containing the following properties:
    score - The competitor's score for the event in which they won a medal.
    worldRecord - Boolean indicating if the competitor set a new world record for this event.
    olympicRecord - Boolean indicating if the competitor set a new Olympic record for this event.
    type - The type of competitor, with possible values of 'country' or 'athlete.'
    athlete - Object containing athlete details if the type of competitor is an athlete.
    country - Object containing country details if the type of competitor is a country.
    Back to top

     

    Sample Response

    XML

    The following XML output was rendered with an internal key calling:
    http://api.espn.com/v1/sports/olympics/countries/cro/medals?season=summer&dates=2008&enable=competitions&_accept=text/xml&apikey=:yourkey.

     

    JSON

    The following JSON output was rendered with an internal key calling:
    http://api.espn.com/v1/sports/olympics/countries/cro/medals?season=summer&dates=2008&enable=competitions&apikey=:yourkey.

    Back to top

  • Sample Code

    JavaScript
    
			// Example JSONP request with jQuery
			$.ajax({
				url: "http://api.espn.com/v1/sports/news/headlines",
				data: {
					// enter your developer api key here
					apikey: "{api key}",
					// the type of data you're expecting back from the api
					_accept: "application/json"
				},
				dataType: "jsonp",
				success: function(data) {
					// create an unordered list of headlines
					var ul = $('<ul/>');
					$.each(data.headlines, function() {
						var li = $('<li/>').text(this.headline);
						ul.append(li)
					});
					// append this list to the document body
					$('body').append(ul);
				},
				error: function() {
					 // handle the error
				}
			});

Medals in Action

Browse Other Data

Additional Help

version 23 as of 2 months ago by Chris Jason