ESPN News Content

News and Headlines

Sports should always be front page news
  • The ESPN Headlines API allows you to interact with ESPN's various news stories. ESPN publishes hundreds of unique pieces of text content each day, covering dozens of sports and hundreds of athletes and teams.

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

    Availability
    Public Strategic Partner ESPN
  • The ESPN Headlines API accepts a GET request.

    Users have the option of requesting an editorially-selected collection of ESPN Headlines content, or a "fire hose" of content relevant to a particular sport or section on ESPN.

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

    Sample Headlines Requests

    Action URI Description
    GET http://api.espn.com/v1/sports/news/headlines/top Top editorially-curated news as shown on ESPN.com home page.
    GET http://api.espn.com/v1/sports/news/headlines Top editorially-curated news aggregated across all sports.
    GET http://api.espn.com/v1/sports/basketball/nba/news/headlines Top editorially-curated NBA news.
    GET http://api.espn.com/v1/sports/basketball/nba/news "Fire hose" of NBA-related news.
    GET http://api.espn.com/v1/sports/basketball/nba/news?dates=20100219 NBA news published on a specific date.
    GET http://api.espn.com/v1/sports/soccer/fifa.olympics/news Olympics soccer news from current day.
    GET http://api.espn.com/v1/sports/soccer/eng.1/news/headlines Top editorially-curated soccer news for the Barclays Premier League.
    GET http://api.espn.com/v1/sports/baseball/mlb/news/headlines?lang=es Top editorially-curated MLB news in Spanish, as determined by ESPNDeportes.com.
    GET http://api.espn.com/v1/fantasy/football/news Current day's Fantasy Football news from ESPN's experts.
    GET http://api.espn.com/v1/sports/news/headlines/top?lang=es&region=ar Top editorially-curated sports news in Spanish-speaking Argentina, as determined by ESPNDeportes.com.
    GET http://api.espn.com/v1/sports/news/6277112 Full text for a specific story. Subject to access tier.
  • Quick Navigation

    Resources

    Resource Name Description Availability
    public strategic
    partner
    espn
    /cities News from ESPN's regional City sites. Currently includes Boston, Chicago, Dallas, Los Angeles, and New York.
    /cities/boston News from ESPNBoston.com
    /cities/chicago News from ESPNChicago.com
    /cities/dallas News from ESPNDallas.com
    /cities/los-angeles News from ESPNLA.com
    /cities/new-york News from ESPNNewYork.com
    /espnw News as published on espnW.com, ESPN's primary destination for women's sports
    /fantasy News and analysis from ESPN's Fantasy experts, covering Fantasy Football, Fantasy Baseball, Fantasy Basketball, Fantasy Hockey, and more.
    /fantasy/baseball Fantasy Baseball
    /fantasy/basketball Fantasy Basketball
    /fantasy/football Fantasy Football
    /fantasy/hockey Fantasy Hockey
    /magazine ESPN Magazine
    /sports/action-sports X Games
    /sports/action-sports/bmx X Games BMX
    /sports/action-sports/moto-x X Games Moto X
    /sports/action-sports/skateboarding X Games Skateboarding
    /sports/action-sports/skiing X Games Skiing
    /sports/action-sports/snowboarding X Games Snowboarding
    /sports/action-sports/snowmobiling X Games Snowmobiling
    /sports/action-sports/surfing X Games Surfing
    /sports/action-sports/rally X Games Rally
    /sports/baseball/mlb Major League Baseball (MLB)
    /sports/basketball/mens-college-basketball NCAA Men's College Basketball
    /sports/basketball/nba National Basketball Association (NBA)
    /sports/basketball/wnba Women's National Basketball Association (WNBA)
    /sports/basketball/womens-college-basketball NCAA Women's College Basketball
    /sports/boxing Boxing
    /sports/football/college-football NCAA College Football
    /sports/football/nfl National Football League (NFL)
    /sports/golf Golf
    /sports/hockey/nhl National Hockey League (NHL)
    /sports/horse-racing Horse Racing
    /sports/mma Mixed Martial Arts
    /sports/olympics Olympic sports
    /sports/racing Auto Racing
    /sports/racing/nascar NASCAR racing
    /sports/soccer Professional soccer
    /sports/soccer/:leagueName Specific professional soccer league. Use a helper API call for a complete list of supported soccer leagues.
    /sports/tennis Tennis
    Back to top

     

    Methods

    Method Description Availability
    public strategic
    partner
    espn
    /news Most recent news for current date.
    /news/headlines Top stories as selected by ESPN editorial staff.
    /news/headlines/featured Featured long-form journalism as selected by ESPN. Only applicable to /sports resource.
    /news/headlines/top Top stories as shown on ESPN.com home page. Only applicable to /sports resource.
    /athletes/:athleteId/news Stories about a particular player/athlete. Only applicable to /sports/:sportName/:leagueAbbrev resource.
    /teams/:teamId/news Stories about a particular team. Only applicable to /sports/:sportName/:leagueAbbrev resource.
    /news/:id Data associated with a specific story.
    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 strategic
    partner
    espn
    dates Integer in the form of "yyyymmdd" to get news for a particular date. Not applicable to the /news/headlines and /news/headlines/top methods.
    insider
    yes default value, includes premium and free content
    no premium content from the results set
    only only premium content
    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).
    inlines Array of inline objects containing HTML markup for inline tables.
    disable Optional flag to disable specific information, with the following options. Accepts a single value or a comma delimited string of values (i.e. disable=a,b,c).
    audio Disables the 'audio' node, if it exists for the story.
    categories Disables the 'categories' array, if it exists for the story.
    keywords Disables the 'keywords' node, if it exists for the story.
    mobileStory Disables the mobile story text, if it exists for the story.
    related Disables the 'related' node, if it exists for the story.
    story Disables the story text.
    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
    region Can be used in conjunction with the lang query string parameter to return focused headlines for a particular region, where available. Current supported regions are listed below:
    ar Argentina. Can only be used with lang=es and sports/soccer/news/headlines/top and /sports/news/headlines/top methods.
    co Columbia. Can only be used with lang=es and sports/soccer/news/headlines/top and /sports/news/headlines/top methods.
    gb Great Britain. Can only be used with lang=en and sports/soccer/news/headlines/top method.
    mx Mexico. Can only be used with lang=es and sports/soccer/news/headlines/top and /sports/news/headlines/top methods.
    us USA. Default region.
    ve Venezuela. Can only be used with lang=es and sports/soccer/news/headlines/top and /sports/news/headlines/top methods.

    Back to top

     

  • Quick Navigation

    Returned Data

    Requests to the ESPN Headlines API return the following data:

    Element Description Availability
    public strategic
    partner
    espn
    title Title tag/meta title of a story.
    headline The story headline.
    description A 1-2 sentence summary/tease of the article.
    source The news source, e.g. ESPN.com News, AP, etc.
    byline The author. Not applicable to all stories.
    keywords Free form text input of keywords related to the story.
    categories Structured collection of keyword meta data, each with the following data:
    description The full name associated with the category.
    links Links to the specific API call and Web and Mobile URLs for the data.
    type The type of category, e.g. sport, team, league, or athlete.
    sportId The API id for the sport.
    leagueId The API id for the league (if applicable).
    teamId The API id for the team (if applicable).
    athleteId The API id for this athlete (if applicable).
    uid A globally unique string identifier for the sports entity in ESPN's systems.
    linkText Short text suitable for use in HTML anchor tags.
    shortLinkText Shorter version of link text suitable for use in HTML anchor tags, if available.
    published The date the story was first published, expressed in standard DateTime data type ("yyyy-MM-ddTHH:mm:ssZ").
    lastModified Last time the story was updated, expressed in standard DateTime data type ("yyyy-MM-ddTHH:mm:ssZ").
    premium Refers to whether a piece of content is ESPN Insider (premium). Possible values are "true" or "false".
    gameId Unique ID of the game in ESPN's system. Not applicable to all stories.
    type The content type of the story, according to ESPN's publishing classifications.
    id Unique content ID for the story in ESPN's publishing system.
    inlines When enabled, returns an array of inline objects containing markup for inline tables. Each inline object contains the following properties:
    body Inline object markup.
    related A collection of related content, each with the following data:
    id Unique content ID for the story
    title Title tag/meta title of a story
    links Link to the Headlines API, Web, and Mobile locations for the story.
    images A collection of images related to the story, each with the following data:
    name The title for the image.
    url The URL for the image.
    alt ALT text if available.
    caption A caption for the image if available.
    type Indicates the type of image. Possible values include inline (sidebar images that can be included in story body), video (thumbnail of the embedded video), and header (main image that can be used to feature the story).
    credit Any copyright information associated with the image.
    width The image width.
    height The image height.
    audio A collection of audio clips related to the story, each with the following data:
    id Unique content ID for the audio clip.
    title Title tag/meta title of the audio clip.
    description Short description of the audio clip.
    link Link to the playable Web location of the audio clip.
    video A collection of video clips related to the story, each with the following data:
    id Unique content ID of video clip in ESPN's publishing system.
    links Link to the playable version of the video on ESPN.com.
    title The title of the video.
    description A brief description of the video content.
    thumbnail URL to an associated thumbnail image for the video.
    links Objects containing links to both API hypermedia and Web/Mobile URLs if available
    web Object containing Web-optimized URL to story
    mobile Object containing Mobile-optimized URL to story
    api Object containing links to related API calls for story
    story The text of the story.
    mobileStory Mobile-optimized text of the story, if available.
    Back to top

     

    Sample Response

    XML

    The following XML output was rendered with a public developer key calling:
    http://api.espn.com/v1/sports/basketball/nba/news/headlines?_accept=text/xml&limit=5&apikey=:yourkey.

     

    JSON

    The following JSON output was rendered with a public key calling:
    http://api.espn.com/v1/sports/basketball/nba/news/headlines?limit=5&apikey=:yourkey.

    Back to top
  • Sample Code

    JavaScript