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 Optional flag to return news for a specific date. Accepts an integer date in the form "yyyymmdd". For example, dates=20140224. Not applicable to the /news/headlines and /news/headlines/top methods.
    disable Optional flag to disable specific information, with the following options. Accepts a single value or a comma-delimited string of values. For example, disable=audio,categories.
    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.
    enable Optional flag to enable specific information, with the following options. Accepts a single value or a comma-delimited string of values.
    authors Returns an array of author information for the content, when available.
    inlines Returns an array of objects containing HTML markup for inline tables, when available.
    peers Returns additional image sizes in a peers array within an image object, when available. Use the peerimagesizes parameter to filter which sizes are returned.
    insider Optional flag to specify whether ESPN Insider premium content is included in the results. Default is yes and the API returns both premium and free content if you do not include the insider parameter in the request. Accepts the following values:
    yes Returns both premium and free ESPN Insider content. Default value.
    no Removes premium content from the results.
    only Returns only premium content in the results.
    lang Optional flag to return content in the specified language. Note: not all content is available in multiple languages and will return in English if no alternative is available. Supported values include the following:
    en English. Default language.
    es Spanish
    peerimagesizes Optional flag to filter returned image sizes when the "enable=peers" parameter is used. Accepts a string value representing the desired image size. For example, "enable=peers&peersimagesizes=110x110,1296x1296".
    publishedkey Optional flag to allow fetching content via published key. Accepts a string value representing the key.
    region Optional flag used in conjunction with the lang parameter to return focused content for a particular region, where available. For example, lang=es&region=ar. Supported regions and methods include the following:
    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 story data in a headlines: array that contains the following core properties:

    Element Description Availability
    public strategic
    partner
    espn
    headline String headline for the content.
    type String description of the content type, according to ESPN's publishing classifications.
    related Array containing related content objects. See the Related Object for details.
    inlines Array of objects containing markup for inline tables. Returned only when the "enable=inlines" parameter is used. See the Inlines Object for details.
    id Integer content ID for the story in ESPN's publishing system.
    authors Array containing information about the authors of an story, when available and the "enable=authors" parameter is used. See the Authors Object for details.
    story String containing the full text of the story. May contain inline HTML markup.
    title String meta title of the content.
    byline String author attribution for the story.
    linkText String suitable for content description in HTML anchor tags.
    description String containing a 1-2 sentence summary/tease of the content.
    published Timestamp indicating when the story was first published.
    video Array of video objects. See the Video API for details.
    keywords Array of keyword strings for topics related to the story.
    lastModified Timestamp indicating the last time the story was updated.
    premium Boolean indicating whether the story is premium ESPN Insider content.
    secondaryDescription String sub-heading or additional description.
    links Object containing platform-optimized links to the content, if available. See the Links Object for details.
    source String description of the news source. For example, "ESPN The Magazine".
    images Array of objects containing images related to the story, when available. See the Images Object for details.
    categories Array of objects containing keyword metadata related to the story. See the Categories Object for details.
    shortLinkText String suitable for content description in HTML anchor tags. A short, alternate version of linkText.
    audio Array of objects containing audio recordings related to the story, when available. See the Audio Object for details.
    Back to top

    Audio Object

    Element Description Availability
    public strategic
    partner
    espn
    id Integer content ID for the audio item in ESPN's publishing system.
    title String title or headline for the audio item. For example, "Carmen & Jurko: Pau Gasol".
    description String description of the audio item.
    links Object containing platform-optimized links to the content, if available.
    Back to top

    Authors Object

    Element Description Availability
    public strategic
    partner
    espn
    firstName String first name of the author.
    lastName String last name of the author.
    displayName String combined full first and last name of the author.
    shortName String containing first initial and last name of the author.
    twitterUserName String containing the Twitter handle for the author. For example, "@CraigCustance".
    biography String containing brief biographical notes about the author. May contain inline HTML markup.
    images Array of objects containing headshots for the author. See the Images Object for details.
    links Object containing a link to the author's profile page on the ESPN web site.
    sourceLine String description of author's publisher or expertise.
    contactInfo String containing email address or contact URL.
    Back to top

    Categories Object

    Element Description Availability
    public strategic
    partner
    espn
    description String description of the related topic. For example, "College Football".
    type String description of the category type. Possible values include "athlete" "fantasyPlayer", "fantasyTeam", "league", "sport" or "team".
    sportId Integer ID of the related sport.
    leagueId Integer ID of the related league, when the type is "league".
    league Object containing the id and description properties along with links for league content, when the type is "league".
    uid A globally unique string identifier for the sports entity in ESPN's systems.
    teamId Integer ID of the related team, when the type is "team".
    team Object containing id and description properties along with links for team content, when the type is "team".
    athleteId Integer ID of the related athlete, when the type is "athlete".
    athlete Object containing id and description properties along with links for athlete content, when the type is "athlete".
    fantasyPlayerId Integer ID of the related fantasy athlete, when the type is "fantasyPlayer".
    fantasyTeamId Integer ID of the related fantasy team, when the type is "fantasyTeam".
    Back to top

    Images Object

    Element Description Availability
    public strategic
    partner
    espn
    height Integer indicating image height in pixels.
    alt String specifying ALT text, if available.
    width Integer indicating image width in pixels.
    name String title for the image.
    caption String caption for the image, if available.
    type String indicating 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 String containing copyright information associated with the image.
    url The URL for the image.
    peers Array of objects containing alternate sizes for the image, if available. Enabled when the "enable=peers" parameter is used. Filter results by size with the peerimagesizes parameter. Objects included in the array follow the same key-value pattern as other Images objects.
    Back to top

    Inlines Object

    The inlines array containing markup for inline content elements such as pullquotes is included in the response when the "enable=inlines" parameter is used. The array may include zero or more objects that contain the following properties. body and type are included for all inline objects. Objects of type "Module" may contain additional properties.

    Element Description Availability
    public strategic
    partner
    espn
    body String containing the content. May include inline HTML markup.
    byline String attribution for the content.
    moduleType String description of the content's intended use. For example, "pullquote".
    images Array of objects containing images related to the story, when available. See the Images Object for details.
    type String describing the type of markup. For example, "BareHTML".
    Back to top
    Element Description Availability
    public strategic
    partner
    espn
    api Object containing links to related API calls for the content.
    web Object containing URLs for web-optimized content.
    mobile Object containing URLs for mobile-optimized content.
    app Object containing URLs for an app-related feed for the content.
    source Object containing URLs for various non-optimized, source content formats. Typically associated with video content.
    Back to top
    Element Description Availability
    public strategic
    partner
    espn
    id Integer content ID for the related story.
    headline String headline for the related story.
    title String meta title of the content.
    linkText Short text suitable for use in HTML anchor tags.
    premium Boolean indicating whether the related story is premium ESPN Insider content.
    description String description or lede for related story.
    images Array of objects containing images related to the story, when available. See the Images Object for details.
    links Object containing platform-optimized links to the content, if available. See the Links Object for details.
    type String description of the content type.
    Back to top

     

    Sample Response

    JSON

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

    Back to top
  • Sample Code

    JavaScript