Push Feeds
Streamline access to live game updates with MLB Push feeds
With our RESTful endpoints, you make API requests whenever you need updated data. Push feeds, however, allow you to open a single connection and receive continuous live updates as data changes. Once established, this connection remains open and streams updates in real time.
Push feeds are an efficient option for consuming live game data, as they eliminate the need to manage pull frequency and instead allow your application to listen for updates as they occur.
RESTful & Push
Each Push update is delivered as a JSON payload that mirrors the structure of its corresponding RESTful MLB API endpoint. Push game payloads provide updates to events and statistics, but do not include game status changes, which should continue to be tracked using schedule-based RESTful feeds.
Below are the Push endpoints alongside their RESTful counterparts.
Push Feed | RESTful Counterpart |
|---|---|
| Push Events | Game Play-by-Play |
| Push Statistics | |
| Push Linescores | Game Boxscore |
| Push Probable Pitchers | Probable pitcher data available in Game Summary endpoints. |
Push feeds complement the RESTful MLB API and do not provide a stateful session. If a Push connection is interrupted, use the corresponding RESTful endpoint to recover any missed data. While Push feeds generally align with RESTful endpoints, RESTful feeds remain the authoritative source for complete MLB data coverage.
Access
MLB Push feeds are an add-on service, and unavailable in the self-issued MLB trial within your account. Reach out to a sales representative for trial access.
MLB Push feeds are available for Sportradar Realtime customers only
Make a Request
Each Push feed starts with a URL request, as with our other RESTful API endpoints.
curl -L -X GET 'https://api.sportradar.com/mlb/{access_level}/stream/{language_code}/{push_feed}/subscribe' \
-H 'x-api-key: {your_api_key}'When constructed, the above call opens up an HTTP redirect connection, returning all Push data for the requested feed. To filter results to a smaller data set include an optional query string.
There are no restrictions on the number of connections you may have open. Feel free to filter requests to individual games and close the connections when games complete, or keep a single unfiltered connection open indefinitely.
Visit the feed endpoint pages for complete syntax instructions.
Filtering
By default, a Push feed will provide all data available. For example, a Push Events would stream all MLB games in progress to your application. If needed, you can filter the data returned by including query strings.
For example, let's say you want to restrict your connection to one MLB game in progress. Construct your call as normal and add the unique game id to the query string.
Here's an example:
curl -L -X GET 'https://api.sportradar.com/mlb/trial/stream/en/events/subscribe?&status=inprogress&match=sd:match:673b459c-7506-4c11-9273-1b9502537f1d' \
-H 'x-api-key: {your_api_key}'Visit the feed endpoints pages for complete query string syntax instructions.
Technical Requirements
To accept data from our Push feeds, ensure that your application can:
- Follow an HTTP redirect, or use the location provided in the feeds header within one minute of your initial request.
- Accept HTTP data transfer encoded as chunked.
Payloads
Our Push services are delivered by HTTP Streaming with chunked encoding, also commonly called HTTP Chunked. The streaming of data is based on long HTTP response. Chunked streaming allows you to act on the chunks immediately instead of waiting or requesting a full file.
When new feed content is available, the server pushes that information out to your client. When no new information is available on a feed, a heartbeat message is sent every 5 seconds to keep the connection active.
Messages are delivered in JSON format only.
{
"heartbeat":{
"interval":5000
}
}{
"heartbeat":{
"interval":5000
}
}{
"heartbeat":{
"interval":5000
}
}{
"payload":{
"game":{
"id":"1506ae41-f6e1-4d94-bd5a-5adcf6a3a967",
"status":"closed",
"coverage":"full",
"game_number":1,
"double_header":false,
"entry_mode":"STOMP",
"mlb_id":"718777",
"day_night":"D",
"scheduled":"2023-03-30T18:20:00+00:00",
"home_team":"55714da8-fcaf-4574-8443-59bfb511a524",
"away_team":"dcfd5266-00ce-442c-bc09-264cd20cf455",
"home":{
"name":"Cubs",
"market":"Chicago",
"abbr":"CHC",
"id":"55714da8-fcaf-4574-8443-59bfb511a524",
"runs":4,
"hits":6,
"errors":1
},
"away":{
"name":"Brewers",
"market":"Milwaukee",
"abbr":"MIL",
"id":"dcfd5266-00ce-442c-bc09-264cd20cf455",
"runs":0,
"hits":4,
"errors":1
}
},
"event":{
"id":"40ce37f0-24fe-4abe-8d9c-bee4b6167102",
"type":"pitch",
"inning":3,
"inning_half":"T",
"sequence_number":98,
"sequence":1680202550928,
"hitter_id":"42cb5171-ffa3-4600-9c41-dbc3805206ea",
"atbat_id":"894a5399-585b-4966-93a1-8370a3c3e24f",
"outcome_id":"bAB",
"status":"official",
"created_at":"2023-03-30T18:55:50+00:00",
"updated_at":"2023-04-04T23:24:25+00:00",
"wall_clock":{
"start_time":"2023-03-30T18:55:38+00:00",
"end_time":"2023-03-30T18:55:45+00:00"
},
"flags":{
"is_ab_over":false,
"is_bunt":false,
"is_bunt_shown":false,
"is_hit":false,
"is_wild_pitch":false,
"is_passed_ball":false,
"is_double_play":false,
"is_triple_play":false
},
"count":{
"balls":2,
"strikes":2,
"outs":0,
"pitch_count":3
},
"pitcher":{
"id":"cc86d4d3-1618-415e-b7fc-a303f3b8dd6f",
"pitcher_hand":"R",
"hitter_hand":"L",
"pitch_count":39,
"last_name":"Stroman",
"first_name":"Marcus",
"preferred_name":"Marcus",
"jersey_number":"0"
},
"hitter":{
"last_name":"Yelich",
"first_name":"Christian",
"preferred_name":"Christian",
"jersey_number":"22",
"id":"42cb5171-ffa3-4600-9c41-dbc3805206ea"
},
"runners":[
"\\"{
"id":"45d9ee07-705d-4d91-8131-264ab0cc8af4",
"starting_base":2,
"ending_base":2,
"outcome_id":"",
"out":false,
"last_name":"Turang",
"first_name":"Brice",
"preferred_name":"Brice",
"jersey_number":"0"
}
]
}
},
"locale":"en",
"metadata":{
"league":"MLB",
"match":"sd:match:1506ae41-f6e1-4d94-bd5a-5adcf6a3a967",
"status":"closed",
"inning":3,
"inning_half":"T",
"event_type":"pitch",
"event_category":"pitch",
"locale":"en",
"operation":"update",
"version":"v6.5"
}
}{
"payload":{
"game":{
"id":"db073916-8fae-4672-a160-061b2892c17c",
"status":"inprogress",
"coverage":"full",
"game_number":1,
"double_header":false,
"entry_mode":"STOMP",
"mlb_id":"718710",
"day_night":"N",
"scheduled":"2023-04-04T23:05:00+00:00",
"home_team":"a09ec676-f887-43dc-bbb3-cf4bbaee9a18",
"away_team":"2142e1ba-3b40-445c-b8bb-f1f8b1054220",
"home":{
"name":"Yankees",
"market":"New York",
"abbr":"NYY",
"id":"a09ec676-f887-43dc-bbb3-cf4bbaee9a18",
"runs":0,
"hits":0,
"errors":0
},
"away":{
"name":"Phillies",
"market":"Philadelphia",
"abbr":"PHI",
"id":"2142e1ba-3b40-445c-b8bb-f1f8b1054220",
"runs":1,
"hits":1,
"errors":0
}
},
"event":{
"id":"3457862e-9483-4430-9a0e-b75e92dda03c",
"type":"pitch",
"inning":2,
"inning_half":"T",
"sequence_number":44,
"sequence":1680650663534,
"hitter_id":"169ed0b1-e34b-4f4b-925b-f3288f24a5e7",
"atbat_id":"6ae2a923-ca55-464e-ad8c-3b054cb2617d",
"outcome_id":"kKS",
"status":"official",
"created_at":"2023-04-04T23:24:23+00:00",
"updated_at":"2023-04-04T23:24:36+00:00",
"wall_clock":{
"start_time":"2023-04-04T23:24:16+00:00",
"end_time":"2023-04-04T23:24:30+00:00"
},
"flags":{
"is_ab_over":false,
"is_bunt":false,
"is_bunt_shown":false,
"is_hit":false,
"is_wild_pitch":false,
"is_passed_ball":false,
"is_double_play":false,
"is_triple_play":false
},
"count":{
"balls":0,
"strikes":2,
"outs":0,
"pitch_count":2
},
"pitcher":{
"pitch_type":"SI",
"pitch_speed":91.5,
"pitch_zone":12,
"pitch_x":17,
"pitch_y":-204,
"id":"f7967ff6-16ea-408f-aa90-7d4df691679f",
"pitcher_hand":"R",
"hitter_hand":"R",
"pitch_count":16,
"last_name":"Germán",
"first_name":"Domingo",
"preferred_name":"Domingo",
"jersey_number":"0"
},
"hitter":{
"last_name":"Castellanos",
"first_name":"Nicholas",
"preferred_name":"Nick",
"jersey_number":"8",
"id":"169ed0b1-e34b-4f4b-925b-f3288f24a5e7"
}
}
},
"locale":"en",
"metadata":{
"league":"MLB",
"match":"sd:match:db073916-8fae-4672-a160-061b2892c17c",
"status":"inprogress",
"inning":2,
"inning_half":"T",
"event_type":"pitch",
"event_category":"pitch",
"locale":"en",
"operation":"update",
"version":"v6.5"
}
}Disconnections
Should you cease to receive heartbeat messages, or are disconnected from the Push service for any reason, re-connect using your same initial request.
Metadata
Each payload includes a metadata header message. The metadata includes information on the type of payload and possible filtering options, saving processing and integration time.
"locale":"en",
"metadata":{
"league":"MLB",
"match":"sd:match:1506ae41-f6e1-4d94-bd5a-5adcf6a3a967",
"status":"closed",
"inning":3,
"inning_half":"T",
"event_type":"pitch",
"event_category":"pitch",
"locale":"en",
"operation":"update",
"version":"v6.5" "locale":"en",
"metadata":{
"league":"MLB",
"match":"sd:match:30ad883f-aeaf-4e6b-9fd9-a1cc0b6c4679",
"status":"inprogress",
"team":"sd:team:f246a5e5-afdb-479c-9aaa-c68beeda7af6",
"stats_type":"team",
"stats_category":"fielding",
"locale":"en",
"operation":"update",
"version":"v6.5"Samples
Code Samples
To best utilize Push feeds, see the below code samples in Ruby and Java. These provide an example of a method to consume the feeds. Using these samples will output the feeds content to STDOUT.
For Java, we have also provided a Stream Client to assist your integration.
Note: In the provided Java sample, replace "URL GOES HERE" with the desired Push feed URL.
require 'httpclient'
module Sportradar
module HTTP
module Stream
class Client
attr_reader :url, :logger
def initialize(url, api_key, logger)
@url = url
@logger = logger
@api_key = api_key
@client = ::HTTPClient.new(agent_name: 'SportsData/1.0')
end
def start
@thread ||= Thread.new do
logger.debug "Starting loop"
headers = {
'x-api-key' => @api_key
}
@client.get_content(url, header: headers, follow_redirect: true) do |chunk|
@publisher.publish(::JSON.parse(chunk)) if @publisher
end
logger.debug "finished loop"
end
end
def stop
@thread.terminate if @thread
end
end
end
end
end
package com.sportradar.http.stream.client;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class StreamClient {
private Thread streamThread;
private volatile boolean running = false;
private String apiKey;
public void setApiKey(String apiKey) {
this.apiKey = apiKey;
}
public void stream(String serviceUrl, Handler handler) {
running = true;
streamThread = new Thread(() -> {
try {
URL url = new URL(serviceUrl);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("GET");
connection.setRequestProperty("User-Agent", "SportsData/1.0");
if (apiKey != null && !apiKey.isEmpty()) {
connection.setRequestProperty("x-api-key", apiKey);
}
try (BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
String line;
while (running && (line = reader.readLine()) != null) {
if (!line.trim().isEmpty()) {
handler.handle(line);
}
}
}
} catch (Exception e) {
e.printStackTrace();
}
});
streamThread.start();
}
public void terminate() {
running = false;
if (streamThread != null) {
streamThread.interrupt();
}
}
}
Data Samples
Samples can be found on each individual endpoints page.
Simulations
You can use our API Simulations to open up a continuous Push simulation of a game. This allows you to experience and analyze our data without having to wait for a real game to take place.
ID Updates
All updates to the Push feeds are categorized as an update or a delete. These will be found within metadata.operation.
Updates may be the creation of an event or an update of information to a previous event.
When you receive an event with the same ID as an event that has been previously consumed, it is best practice to replace the data from the previous message with the data consumed in the most recent message.
"locale":"en",
"metadata":{
"league":"MLB",
"match":"sd:match:2a977578-2d14-4924-9d68-6499a735d4e5",
"status":"scheduled",
"event_type":"probable",
"locale":"en",
"operation":"update",
"version":"v6.5" "locale":"en",
"metadata":{
"league":"MLB",
"match":"sd:match:2a977578-2d14-4924-9d68-6499a735d4e5",
"status":"scheduled",
"event_type":"probable",
"locale":"en",
"operation":"delete",
"version":"v6.5"Updated 3 days ago