openapi: 3.0.0 info: title: Google Sports API description: | The Google Sports API returns the sports results Google shows for a team, league or game: recent and upcoming games with scores, venues and UTC start times, league standings with each team's rank and stats, and the details of a single game. **Tabs**: `tab=games` (default) returns a team's or league's games. Games grouped under round headings, such as a league's matchdays, are returned in `game_groups`; other games are returned in `games`. `tab=standings` returns the league table of the current season in `standings`, or of the season passed in `season`. A game's kgmid returns that game in `game_spotlight`, whatever the tab. Google does not serve these tabs for every league: for leagues such as the NBA and the NFL, `tab=standings` without `season` can end in a 503 error and `tab=games` can return only the few games on the team's or league's page. **Cross-linking**: A team or league kgmid is its Freebase ID or Google Knowledge Graph ID on Wikidata. The `kgmid` of each game and team and the `league_kgmid` in the response can be passed as the `kgmid` parameter of a new request, and the `kgmid` of each season in `standings.seasons` as the `season` parameter. **No results**: When Google shows no sports results for the kgmid and tab, the response carries an `error` instead of `sports_results`. So does a `season` of another league. A `season` id Google cannot answer ends in a 503 error. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Google Sports security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Search engine to use schema: type: string enum: ["google_sports"] - name: kgmid in: query required: true description: Knowledge Graph identifier of a team, league or game, starting with /m/ or /g/ schema: type: string pattern: '^/[mg]/\w{1,30}$' maxLength: 33 - name: tab in: query required: false description: Tab of a team or league page to return, its games or the league standings schema: type: string enum: ["games", "standings"] default: "games" - name: season in: query required: false description: Season of the standings, the kgmid of a season in standings.seasons of this kgmid's standings. Requires tab=standings; defaults to the current season schema: type: string pattern: '^/[mg]/\w{1,30}$' maxLength: 33 - name: gl in: query required: false description: Country of the search (two-letter country code) schema: type: string enum: ["af", "al", "dz", "as", "ad", "ao", "ai", "aq", "ag", "ar", "am", "aw", "au", "at", "az", "bs", "bh", "bd", "bb", "by", "be", "bz", "bj", "bm", "bt", "bo", "ba", "bw", "bv", "br", "io", "bn", "bg", "bf", "bi", "kh", "cm", "ca", "cv", "ky", "cf", "td", "cl", "cn", "cx", "cc", "co", "km", "cg", "cd", "ck", "cr", "ci", "hr", "cu", "cy", "cz", "dk", "dj", "dm", "do", "ec", "eg", "sv", "gq", "er", "ee", "et", "fk", "fo", "fj", "fi", "fr", "gf", "pf", "tf", "ga", "gm", "ge", "de", "gh", "gi", "gr", "gl", "gd", "gp", "gu", "gt", "gn", "gw", "gy", "ht", "hm", "va", "hn", "hk", "hu", "is", "in", "id", "ir", "iq", "ie", "il", "it", "jm", "jp", "jo", "kz", "ke", "ki", "kp", "kr", "kw", "kg", "la", "lv", "lb", "ls", "lr", "ly", "li", "lt", "lu", "mo", "mk", "mg", "mw", "my", "mv", "ml", "mt", "mh", "mq", "mr", "mu", "yt", "mx", "fm", "md", "mc", "mn", "ms", "ma", "mz", "mm", "na", "nr", "np", "nl", "nc", "nz", "ni", "ne", "ng", "nu", "nf", "mp", "no", "om", "pk", "pw", "ps", "pa", "pg", "py", "pe", "ph", "pn", "pl", "pt", "pr", "qa", "re", "ro", "ru", "rw", "sh", "kn", "lc", "pm", "vc", "ws", "sm", "st", "sa", "sn", "rs", "sc", "sl", "sg", "sk", "si", "sb", "so", "za", "gs", "es", "lk", "sd", "sr", "sj", "sz", "se", "ch", "sy", "tw", "tj", "tz", "th", "tl", "tg", "tk", "to", "tt", "tn", "tr", "tm", "tc", "tv", "ug", "ua", "ae", "uk", "gb", "us", "um", "uy", "uz", "vu", "ve", "vn", "vg", "vi", "wf", "eh", "ye", "zm", "zw", "gg", "je", "im", "me"] default: "us" - name: hl in: query required: false description: Interface language of the search, used for league names, dates, times and game statuses schema: type: string enum: ["af", "ak", "sq", "am", "ar", "hy", "az", "eu", "be", "bem", "bn", "bh", "xx-bork", "bs", "br", "bg", "km", "ca", "chr", "ny", "zh-cn", "zh-tw", "co", "hr", "cs", "da", "nl", "xx-elmer", "en", "eo", "et", "ee", "fo", "tl", "fi", "fr", "fy", "gaa", "gl", "ka", "de", "el", "kl", "gn", "gu", "xx-hacker", "ht", "ha", "haw", "iw", "hi", "hu", "is", "ig", "id", "ia", "ga", "it", "ja", "jw", "kn", "kk", "rw", "rn", "xx-klingon", "kg", "ko", "kri", "ku", "ckb", "ky", "lo", "la", "lv", "ln", "lt", "loz", "lg", "ach", "mk", "mg", "my", "ms", "ml", "mt", "mv", "mi", "mr", "mfe", "mo", "mn", "sr-me", "ne", "pcm", "nso", "no", "nn", "oc", "or", "om", "ps", "fa", "xx-pirate", "pl", "pt", "pt-br", "pt-pt", "pa", "qu", "ro", "rm", "nyn", "ru", "gd", "sr", "sh", "st", "tn", "crs", "sn", "sd", "si", "sk", "sl", "so", "es", "es-419", "su", "sw", "sv", "tg", "ta", "tt", "te", "th", "ti", "to", "lua", "tum", "tr", "tk", "tw", "ug", "uk", "ur", "uz", "vu", "vi", "cy", "wo", "xh", "yi", "yo", "zu"] default: "en" responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server Error. Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: We could not retrieve results in 90 seconds, or Google could not answer the requested season or tab. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: SearchResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' sports_results: $ref: '#/components/schemas/SportsResults' error: type: string description: Error message if the request failed, e.g. when Google shows no sports results for the kgmid and tab SportsResults: type: object required: [title] properties: title: type: string description: Team, league or game name subtitle: type: string description: Team or league subtitle, such as its league position game_spotlight: $ref: '#/components/schemas/GameSpotlight' games: type: array description: Games of the team or league items: $ref: '#/components/schemas/Game' game_groups: type: array description: Games of the league grouped by round items: $ref: '#/components/schemas/GameGroup' standings: $ref: '#/components/schemas/Standings' Game: type: object required: [kgmid, league, date, start_time, teams] properties: kgmid: type: string description: Knowledge Graph identifier of the game league: type: string description: League name stage: type: string description: Game stage or round date: type: string description: Game date as Google displays it time: type: string description: Game time as Google displays it stadium: type: string description: Stadium name status: type: string description: Game status as Google displays it videos: type: array description: Videos about the game items: $ref: '#/components/schemas/Video' teams: type: array description: The two teams of the game items: $ref: '#/components/schemas/GameTeam' league_kgmid: type: string description: Knowledge Graph identifier of the league start_time: type: string format: date-time description: Start of the game in UTC, in ISO 8601 format GameSpotlight: type: object required: [kgmid, league, date, start_time, teams] properties: kgmid: type: string description: Knowledge Graph identifier of the game league: type: string description: League name stage: type: string description: Game stage or round date: type: string description: Game date as Google displays it time: type: string description: Game time as Google displays it stadium: type: string description: Stadium name city: type: string description: City where the game is played status: type: string description: Game status as Google displays it videos: type: array description: Videos about the game items: $ref: '#/components/schemas/Video' teams: type: array description: The two teams of the game items: $ref: '#/components/schemas/GameTeam' score_table: $ref: '#/components/schemas/ScoreTable' league_kgmid: type: string description: Knowledge Graph identifier of the league start_time: type: string format: date-time description: Start of the game in UTC, in ISO 8601 format GameTeam: type: object required: [name, kgmid] properties: name: type: string description: Team name stats: type: object description: Team win-loss record properties: wins: type: integer description: Number of wins losses: type: integer description: Number of losses score: type: string description: Team score kgmid: type: string description: Knowledge Graph identifier of the team thumbnail: type: string description: URL of the team logo Video: type: object required: [title, link] properties: title: type: string description: Video title link: type: string description: Video URL length: type: string description: Video duration ScoreTable: type: object description: Score breakdown of the game by period properties: headers: type: array description: Table headers items: type: string rows: type: array description: Table rows, one per team items: type: array items: type: string GameGroup: type: object required: [title, games] properties: title: type: string description: Round title games: type: array description: Games of the round items: $ref: '#/components/schemas/Game' Standings: type: object required: [groups] properties: league: type: string description: Competition the standings belong to league_kgmid: type: string description: Knowledge Graph identifier of the league season: type: string description: Season of the standings seasons: type: array description: Seasons available for the league items: $ref: '#/components/schemas/Season' groups: type: array description: Standings tables, one per group or conference items: $ref: '#/components/schemas/StandingsGroup' Season: type: object required: [name, kgmid] properties: name: type: string description: Season name kgmid: type: string description: Knowledge Graph identifier of the season, accepted as the season parameter is_selected: type: boolean description: Whether this is the season of the standings StandingsGroup: type: object required: [teams] properties: title: type: string description: Name of the group or conference teams: type: array description: Teams in standings order items: $ref: '#/components/schemas/StandingsTeam' StandingsTeam: type: object required: [rank, name, kgmid, stats] properties: rank: type: integer description: Position of the team in the table name: type: string description: Team name kgmid: type: string description: Knowledge Graph identifier of the team thumbnail: type: string description: Team logo image as a base64 data URI or a URL stats: type: array description: Team statistics in table column order items: $ref: '#/components/schemas/StandingsStat' StandingsStat: type: object required: [name, short_name] properties: name: type: string description: Statistic name short_name: type: string description: Column heading of the statistic value: type: string description: Statistic value values: type: array description: List of values, such as the results of the team's most recent games items: type: string SearchMetadata: type: object required: [status, created_at] properties: id: type: string description: Unique identifier for the search request status: type: string description: Status of the search request created_at: type: string format: date-time description: Timestamp when the search was created request_time_taken: type: number description: Time taken to make the request in seconds parsing_time_taken: type: number description: Time taken to parse the results in seconds total_time_taken: type: number description: Total time taken for the search in seconds request_url: type: string description: Google Search URL for this team, league or game html_url: type: string description: URL to view HTML results json_url: type: string description: URL to view JSON results SearchParameters: type: object properties: engine: type: string description: Search engine used kgmid: type: string description: Knowledge Graph identifier of the requested team, league or game tab: type: string description: Requested tab season: type: string description: Requested season of the standings hl: type: string description: Interface language of the search gl: type: string description: Country of the search ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong