Sportradar Soccer Push API

openapi: 3.1.0
info:
  title: Sportradar Push Feeds Competitors Soccer Push API
  description: Sportradar's Push Feeds deliver real-time sports data over HTTP using chunked transfer encoding. A single long-lived HTTP connection streams JSON-encoded events, statistics, clock updates, and draft activity for live games. When no new content is available, the server sends a heartbeat message every five seconds to keep the connection alive. Push Feeds are an add-on service available to Sportradar Realtime customers and are intended to complement, not replace, the RESTful Sports Data APIs. Clients must follow HTTP redirects and accept chunked transfer encoding. There are no documented limits on the number of concurrent connections.
  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:
  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
  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'
  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