Sportradar Soccer Push API

openapi: 3.2.0
info:
  title: Sportradar Push Feeds Soccer Push API
  description: Sportradar's Push Feeds deliver real-time sports data over HTTP using chunked transfer encoding.
  version: v1
  contact:
    name: Sportradar Developer Support
    url: https://developer.sportradar.com/docs/read/Home#support
  termsOfService: https://sportradar.com/terms/
servers:
- url: https://api.sportradar.com
  description: Sportradar Push Feeds Production Server
security:
- apiKey: []
tags:
- name: Soccer Push
  description: Soccer Push Feeds deliver real-time match events and statistics over HTTP chunked streaming for 500+ competitions worldwide.
  externalDocs:
    url: https://developer.sportradar.com/soccer/docs/soccer-ig-push
paths:
  /soccer/{access_level}/{version}/stream/events/subscribe:
    get:
      operationId: subscribeSoccerPushEvents
      summary: Subscribe to Soccer Push Events
      description: Opens a long-lived HTTP chunked connection that streams real-time match events across Sportradar's soccer coverage. Heartbeat messages are sent every five seconds when no new events are available. Use the optional sport_event_id filter to limit the stream to a single match.
      tags:
      - Soccer Push
      parameters:
      - $ref: '#/components/parameters/accessLevelParam'
      - $ref: '#/components/parameters/soccerVersionParam'
      - name: sport_event_id
        in: query
        required: false
        description: Limit the stream to a specific sport event identifier.
        schema:
          type: string
      - name: format
        in: query
        required: false
        description: Response format. Defaults to JSON.
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          $ref: '#/components/responses/PushStream'
        '302':
          $ref: '#/components/responses/PushRedirect'
        '401':
          description: Unauthorized - invalid or missing API key.
        '403':
          description: Forbidden - account is not entitled to Realtime push feeds.
  /soccer/{access_level}/{version}/stream/statistics/subscribe:
    get:
      operationId: subscribeSoccerPushStatistics
      summary: Subscribe to Soccer Push Statistics
      description: Opens a long-lived HTTP chunked connection that streams real-time soccer match statistics. Heartbeat messages are sent every five seconds when no new statistics are available.
      tags:
      - Soccer Push
      parameters:
      - $ref: '#/components/parameters/accessLevelParam'
      - $ref: '#/components/parameters/soccerVersionParam'
      - name: sport_event_id
        in: query
        required: false
        description: Limit the stream to a specific sport event identifier.
        schema:
          type: string
      - name: format
        in: query
        required: false
        description: Response format. Defaults to JSON.
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          $ref: '#/components/responses/PushStream'
        '302':
          $ref: '#/components/responses/PushRedirect'
        '401':
          description: Unauthorized - invalid or missing API key.
        '403':
          description: Forbidden - account is not entitled to Realtime push feeds.
components:
  parameters:
    accessLevelParam:
      name: access_level
      in: path
      required: true
      description: Sportradar access level for the requested package. Trial accounts use 'trial'; production customers use 'production'.
      schema:
        type: string
        enum:
        - trial
        - production
    soccerVersionParam:
      name: version
      in: path
      required: true
      description: Sportradar Soccer API version (for example, v4).
      schema:
        type: string
  responses:
    PushRedirect:
      description: Push Feed subscriptions begin with an HTTP redirect to the streaming origin. Clients must follow the redirect within one minute of the initial request.
      headers:
        Location:
          description: URL of the streaming origin to follow.
          schema:
            type: string
            format: uri
    PushStream:
      description: Successful subscription. The server returns an open HTTP connection with Transfer-Encoding chunked and continuously emits JSON messages. Heartbeat messages are emitted every five seconds when no other content is available.
      headers:
        Transfer-Encoding:
          description: Always 'chunked' for Push Feed responses.
          schema:
            type: string
            enum:
            - chunked
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/Heartbeat'
            - $ref: '#/components/schemas/PushPayload'
  schemas:
    PushPayload:
      type: object
      description: Generic envelope describing a Push Feed payload. Each Sportradar package defines the concrete metadata and payload shape; refer to the package-specific documentation for field-level details.
      properties:
        metadata:
          type: object
          description: Feed metadata describing the package, sport, event, and sequence information for the message.
          additionalProperties: true
        payload:
          type: object
          description: Package-specific payload such as an event, statistics update, clock update, or draft activity.
          additionalProperties: true
    Heartbeat:
      type: object
      description: Heartbeat message emitted every five seconds when no new content is available on the stream. Used by clients to confirm the connection is still healthy.
      properties:
        heartbeat:
          type: object
          properties:
            from:
              type: integer
              description: Start of the heartbeat window as a Unix timestamp.
            to:
              type: integer
              description: End of the heartbeat window as a Unix timestamp.
            interval:
              type: integer
              description: Heartbeat interval in seconds.
              examples:
              - 5
            type:
              type: string
              description: Feed type the heartbeat is associated with.
              examples:
              - events
              - statistics
              - clock
              - pulse
            package:
              type: string
              description: Sportradar package emitting the heartbeat.
              examples:
              - soccer-v4
              - nfl
              - nba
              - nhl
              - wnba
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Sportradar Push Feeds require an API key passed in the x-api-key request header. Push entitlements are tied to Realtime customer accounts.
externalDocs:
  description: Sportradar Push Feeds Documentation
  url: https://developer.sportradar.com/getting-started/docs/get-started