Soccerway APIsoccerway.com ↗
Retrieve Soccerway editorial match reports — headline, author, body paragraphs, timestamps, and images — for any match via a single API endpoint.
What is the Soccerway API?
The Soccerway Match Report API exposes 10 structured fields from the editorial report published on any Soccerway match page's Report tab. The single get_match_report endpoint accepts a Soccerway match identifier and returns the headline, author byline, UTC-timestamped publication and edit times, an ordered array of plain-text body paragraphs, a joined full-text field, lead image metadata, and the report's own identifier.
curl -X GET 'https://api.parse.bot/scraper/1a991c73-7eea-4abb-b333-4b89d9fff23e/get_match_report?match_id=A7Ob65ig' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace soccerway-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Soccerway match-report retrieval with typed field access."""
from parse_apis.soccerway_com_api import Soccerway, ReportNotFound
client = Soccerway()
# Fetch the editorial match report for a known Premier League fixture.
try:
report = client.match_reports.get(match_id="A7Ob65ig")
except ReportNotFound:
print("No report published for this match yet.")
raise SystemExit
# Headline and byline
print(report.headline)
print(f"by {report.author}, published {report.published_at.isoformat()}")
# Lead image (may be absent for some reports)
if report.lead_image is not None:
print(f"Image: {report.lead_image.url} ({report.lead_image.credit})")
# Body paragraphs
for paragraph in report.paragraphs:
print(paragraph[:120])
# Teams and players mentioned in the article
for entity in report.mentioned_entities:
print(f" [{entity.type}] {entity.name} (id={entity.id})")
print("exercised: match_reports.get")
Returns the editorial match report for one match, as shown on the match page's Report tab: the headline, author, publication and last-edit timestamps (UTC ISO 8601), the body as an ordered list of plain-text paragraphs plus a joined text field, the lead image, any inline body images (alt text and credit), and the teams and players hyperlinked in the body with their Soccerway ids. One report per match; the call costs a fixed three round trips. When the site has no report for the given match id (typical for matches not yet played, lower-profile fixtures, or an unknown id) the endpoint returns a stale_input error of kind input_not_found rather than an empty result.
| Param | Type | Description |
|---|---|---|
| match_idrequired | string | Soccerway match identifier: the 8-character alphanumeric value of the mid query parameter in a match URL (e.g. .../report/?mid=<match_id>). Case-sensitive. |
{
"type": "object",
"fields": {
"text": "all paragraphs joined with blank lines",
"author": "byline / author credit, may be null",
"headline": "report headline",
"match_id": "the match identifier the report belongs to",
"edited_at": "UTC ISO 8601 last-edit time",
"report_id": "Soccerway's identifier of the report article",
"lead_image": "object {url, alt, credit} of the header image, null when none",
"paragraphs": "ordered array of plain-text body paragraphs (links and formatting stripped)",
"is_published": "whether the site marks the report as published",
"published_at": "UTC ISO 8601 publication time",
"inline_images": "array of {alt, credit} for images embedded in the body",
"mentioned_entities": "array of {type (team|player), name, slug, id} for teams and players linked in the body"
},
"sample": {
"data": {
"text": "Bournemouth missed another chance to secure their first Premier League (PL) victory under new boss Marco Rose, squandering a two-goal lead away to Newcastle United to draw 2-2 and passing up the chance to make it three successive wins at St. James’ Park.\n\nFlashscore Man of the Match: Marcus Tavernier (Bournemouth)",
"author": "Chris Wilson",
"headline": "Late Rambo sucker punch denies Cherries",
"match_id": "A7Ob65ig",
"edited_at": "2026-09-05T13:26:23Z",
"report_id": "j5d4WyPo",
"lead_image": {
"alt": "Late Rambo sucker punch denies Cherries",
"url": "https://livesport-ott-images.ssl.cdn.cra.cz/r1200x675q60/6750b497-1ddf-41c3-a5b6-675554acc326.jpeg",
"credit": "IAN MACNICOL / GETTY IMAGES EUROPE / GETTY IMAGES VIA AFP"
},
"paragraphs": [
"Bournemouth missed another chance to secure their first Premier League (PL) victory under new boss Marco Rose, squandering a two-goal lead away to Newcastle United to draw 2-2 and passing up the chance to make it three successive wins at St. James’ Park.",
"Flashscore Man of the Match: Marcus Tavernier (Bournemouth)"
],
"is_published": true,
"published_at": "2026-09-05T13:26:19Z",
"inline_images": [
{
"alt": "Momentum",
"credit": "Flashscore"
}
],
"mentioned_entities": [
{
"id": "OtpNdwrc",
"name": "Bournemouth",
"slug": "bournemouth",
"type": "team"
},
{
"id": "jFqXIRZj",
"name": "Marcus Tavernier",
"slug": "tavernier-marcus",
"type": "player"
}
]
},
"status": "success"
}
}About the Soccerway API
What the endpoint returns
The get_match_report endpoint takes one required parameter — match_id, the 8-character alphanumeric value from the mid query parameter in any Soccerway match URL — and returns the full editorial write-up for that match. The response includes headline, author (nullable), published_at, edited_at (both UTC ISO 8601), is_published, and the article's own report_id.
Body text fields
The body content is returned in two complementary forms. paragraphs is an ordered array of plain-text strings with links and HTML formatting stripped, preserving reading order. text concatenates those same paragraphs joined by blank lines — useful when you need the full body in a single string without iterating the array.
Image data
lead_image is an object with url, alt, and credit sub-fields representing the header image attached to the report. It is null when no lead image has been published for that match. The endpoint does not expose inline body images separately from the lead image field.
The Soccerway API is a managed, monitored endpoint for soccerway.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when soccerway.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official soccerway.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Archive match narratives by storing
paragraphsandpublished_atfor a historical corpus of football reporting. - Display the full match write-up alongside live scores in a sports news aggregator, using
headlineandtext. - Track editorial updates to a report by comparing
published_atagainstedited_atto detect post-publication changes. - Pull the
lead_imageURL andcreditto render illustrated match summaries in a media dashboard. - Attribute match coverage correctly by extracting the
authorbyline for journalist-level analytics. - Check
is_publishedbefore indexing a report to avoid storing draft or unpublished content. - Correlate
report_idwith external databases to deduplicate match articles across football data sources.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Soccerway offer an official developer API?+
What does `get_match_report` return when a match has no editorial report?+
is_published being false and the text fields being empty or null. The report_id and author fields may also be null in that case.Does the API return player and team mentions extracted from the report body?+
paragraphs and text) from which you can parse mentions yourself, but structured entity extraction for named teams or players is not a dedicated response field. You can fork this API on Parse and revise it to add a named-entity extraction layer.Is inline image data from the report body available?+
url, alt, and credit. Inline images embedded within the body are not exposed as separate fields. You can fork this API on Parse and revise it to surface inline body images if your use case requires them.How do I find the correct `match_id` to pass to the endpoint?+
match_id is the 8-character alphanumeric value of the mid query parameter in any Soccerway match URL. For example, in soccerway.com/matches/.../?mid=3977823a, the value 3977823a is the identifier to use.