openapi: 3.0.1
info:
  title: GoalServe Sports Data Feeds Commentaries Live Scores API
  description: GoalServe live sports data feeds API. All feeds are requested with a standard HTTP GET and return XML by default or JSON when the `json` query parameter is set. Authentication is performed with a unique API access key carried directly in the request path immediately after `/getfeed/`. Access to in-play feeds additionally requires the caller's IP address to be whitelisted in the GoalServe system.
  termsOfService: https://www.goalserve.com/en/terms
  contact:
    name: GoalServe Support
    email: support@goalserve.com
    url: https://www.goalserve.com/en/contact-us
  version: '1.0'
servers:
- url: https://www.goalserve.com/getfeed
  description: GoalServe feed host. The path segment following this base URL is the API access key.
security:
- ApiKeyInPath: []
tags:
- name: Live Scores
paths:
  /{key}/soccernew/home:
    get:
      operationId: getLiveScores
      tags:
      - Live Scores
      summary: Live soccer scores
      description: Returns currently live and recently played soccer matches across all covered leagues, including scores, current minute, goals, cards and substitutions.
      parameters:
      - $ref: '#/components/parameters/Key'
      - $ref: '#/components/parameters/Json'
      - name: cat
        in: query
        required: false
        description: Optional category (league) identifier to filter the live feed to a single competition.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/xml:
              schema:
                type: string
            application/json:
              schema:
                type: object
  /{key}/soccernew/{country}:
    get:
      operationId: getCountryLiveScores
      tags:
      - Live Scores
      summary: Live scores by country
      description: Returns live and recent soccer matches for a single country.
      parameters:
      - $ref: '#/components/parameters/Key'
      - name: country
        in: path
        required: true
        description: Country identifier (e.g. england, spain, italy).
        schema:
          type: string
      - $ref: '#/components/parameters/Json'
      responses:
        '200':
          description: OK
          content:
            application/xml:
              schema:
                type: string
            application/json:
              schema:
                type: object
components:
  parameters:
    Json:
      name: json
      in: query
      required: false
      description: Set to `1` to receive the feed as JSON instead of the default XML.
      schema:
        type: integer
        enum:
        - 1
    Key:
      name: key
      in: path
      required: true
      description: GoalServe API access key path segment.
      schema:
        type: string
  securitySchemes:
    ApiKeyInPath:
      type: apiKey
      in: path
      name: key
      description: Unique GoalServe API access key supplied as the first path segment after `/getfeed/`. Issued on registration; in-play feeds also require the caller's IP address to be whitelisted.