# Flashscore Hockey Scraper - Live Scores, Periods & Stats (`clearfetch/flashscore-hockey-scraper`) Actor

Scrape ice hockey games from Flashscore: fixtures, live scores, final results, period-by-period scores, overtime and shootout outcomes, and match statistics. NHL, KHL, SHL and every domestic league. No proxy, no login.

- **URL**: https://apify.com/clearfetch/flashscore-hockey-scraper.md
- **Developed by:** [Nada Hanad](https://apify.com/clearfetch) (community)
- **Categories:** Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 games

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Flashscore Hockey Scraper - Live Scores, Periods & Stats

Ice hockey results from Flashscore as clean JSON: fixtures, live scores, final results, the score in every
period, and whether a game was settled in regulation, overtime or a shootout. NHL, KHL, SHL, Liiga and the
leagues below them. No login, no API key and no proxy. **$0.001 per game.**

### What data you get

- **Period-by-period scores** that reconcile with the final score, asserted on every finished game in the tests.
- **How the game was decided.** `decidedBy` is `regulation`, `overtime` or `shootout`, and `regulation`
  carries the score after three periods. This matters more than it sounds: a shootout win adds one goal to the
  published total that belongs to no period, so a naive sum is off by one on exactly those games. Anything you
  build on goal totals, from a model to a league table, needs that distinction.
- **Status from Flashscore's own stage codes**, so a game in the second period reads as live, with
  `stageDetail` naming the stage such as `SECOND_PERIOD` or `AFTER_PENALTIES`.
- **Teams and competition** with IDs, three-letter codes, logos and the Flashscore URL.
- **`raw`**: all 47 original feed fields.

### Output example

A game decided in a shootout. Note that the periods total 3-3 while the published score is 4-3:

```json
{
  "matchId": "GQSdbs3B",
  "url": "https://www.flashscore.com/match/GQSdbs3B/",
  "sport": "hockey",
  "status": "finished",
  "stage": "finished",
  "stageDetail": "AFTER_PENALTIES",
  "stageCode": 3,
  "stageDetailCode": 11,
  "startTime": "2026-09-04T16:30:00.000Z",
  "lastUpdate": "2026-09-04T18:49:55.000Z",
  "note": null,
  "tournament": {
    "name": "ELJ",
    "fullName": "CZECH REPUBLIC: ELJ",
    "country": "Czech Republic",
    "phase": null,
    "id": "tKYKpUho",
    "stageId": "jNPXsCBq",
    "path": "/hockey/czech-republic/elj/",
    "url": "https://www.flashscore.com/hockey/czech-republic/elj/"
  },
  "home": {
    "name": "Poruba U20",
    "fullName": "Poruba U20",
    "id": "nufW9uwp",
    "slug": "poruba",
    "url": "https://www.flashscore.com/team/poruba/nufW9uwp/",
    "code": "POR",
    "image": "https://static.flashscore.com/res/image/data/lUNc497k-8M2BM1rJ.png"
  },
  "away": {
    "name": "Kladno U20",
    "fullName": "Kladno U20",
    "id": "Khhv8J7d",
    "slug": "kladno",
    "url": "https://www.flashscore.com/team/kladno/Khhv8J7d/",
    "code": "KLA",
    "image": "https://static.flashscore.com/res/image/data/bFkieS7k-GvfgbSG9.png"
  },
  "score": {
    "home": 4,
    "away": 3,
    "periods": [
      {
        "period": "P1",
        "home": 0,
        "away": 0
      },
      {
        "period": "P2",
        "home": 1,
        "away": 3
      },
      {
        "period": "P3",
        "home": 2,
        "away": 0
      },
      {
        "period": "OT",
        "home": 0,
        "away": 0
      }
    ],
    "regulation": {
      "home": 3,
      "away": 3
    },
    "decidedBy": "shootout"
  },
  "winner": "home",
  "inPlay": false,
  "ok": true,
  "dayOffset": -1,
  "scrapedAt": "2026-09-05T19:25:33.348Z"
}
```

### Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `mode` | string | `matches` | `matches` for fixtures, live scores and results; `matchDetails` for period scores, statistics and head to head. |
| `days` | array | `["0"]` | Day offsets from today, from -7 to 7. A North American evening game lands on the following UTC day. |
| `status` | array | all | `scheduled`, `live`, `finished`, `postponed`, `cancelled` or `interrupted`. |
| `countries` | array | all | For example USA, Canada, Sweden, Finland, Russia. |
| `tournamentFilter` | string | — | Case-insensitive regular expression on the competition name, e.g. `nhl`. |
| `matchIds` | array | — | Details mode: match IDs or full `flashscore.com/match/...` URLs. |
| `details` | array | all three | Details mode: `summary`, `statistics`, `h2h`. |
| `maxItems` | integer | `0` | Stop after this many rows; 0 means no limit. |
| `maxConcurrency` | integer | `5` | Parallel requests in details mode. |
| `timeoutSecs` | integer | `30` | Per-request timeout. |
| `proxyConfiguration` | object | off | Optional. Not needed in normal use. |

### Pricing

**$0.001 per game**, and **$0.01 per game** in details mode however many sections you request. Games that fail or
have no data are free.

### Use cases

- **Modelling**: period-level scoring rates, and overtime and shootout frequency, with the shootout goal kept out
  of the run of play where it belongs.
- **Live scoreboards and bots**: poll for in-progress scores and push updates.
- **Fantasy and prediction games**: fixtures in, results out, including the games that go past regulation.
- **Media**: daily digests with the period breakdown.
- **AI agents**: a tool that answers "which games went to overtime last night".

### Integrations

```bash
curl -X POST "https://api.apify.com/v2/acts/clearfetch~flashscore-hockey-scraper/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"days": ["-1"], "countries": ["USA", "Canada"]}'
```

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("clearfetch/flashscore-hockey-scraper").call(run_input={"days": ["-1"]})

for game in client.dataset(run["defaultDatasetId"]).iterate_items():
    periods = " ".join(f'{p["period"]} {p["home"]}-{p["away"]}' for p in game["score"]["periods"] or [])
    print(game["home"]["name"], game["score"]["home"], "-", game["score"]["away"],
          game["away"]["name"], f'({game["score"]["decidedBy"]})', periods)
```

Works with the Apify integrations for n8n, Make, Zapier, Google Sheets, Slack and webhooks, with scheduled runs,
and with AI agents through the Apify MCP server.

### FAQ

**Why do the periods not add up on some games?** Because it went to a shootout, and the winner's published total
includes the shootout point, which belongs to no period. `decidedBy` tells you which games those are, and the
tests assert the difference is exactly one goal.

**Do I need a proxy?** No. A proxy input exists for completeness.

**Is this legal?** It reads the same public endpoints a browser reads, with no login and no personal data. Scores
are facts. What you do with the data, including redistribution, is your responsibility.

### Changelog

- **1.0.0** (2026-09) — first release: games mode with day ranges and filters, period scores with regulation and
  overtime separated, shootout outcomes identified, details mode with statistics and head to head.

# Actor input Schema

## `mode` (type: `string`):

"Games" returns one row per game for the days you choose. "Game details" takes match IDs and returns period scores, statistics and head-to-head.

## `days` (type: `array`):

Which days to cover, as offsets from today: 0 is today, -1 yesterday, 1 tomorrow. Range -7 to 7. Add several entries to cover a range in one run.

## `status` (type: `array`):

Keep only games in these states. Leave empty for all. Status comes from Flashscore's own stage codes, so a game in the second period counts as live.

## `countries` (type: `array`):

Keep only competitions from these countries or regions, for example USA, Canada, Sweden, Russia. Leave empty for all.

## `tournamentFilter` (type: `string`):

Optional case-insensitive regular expression on the competition name, for example "nhl" or "khl|shl".

## `matchIds` (type: `array`):

Match IDs, or full flashscore.com/match/... URLs. Only used in game details mode.

## `details` (type: `array`):

Sections to fetch per game. Leave empty for all three. Each game is charged once no matter how many sections you pick.

## `maxItems` (type: `integer`):

Stop after this many rows. 0 means no limit.

## `maxConcurrency` (type: `integer`):

Parallel requests in details mode.

## `timeoutSecs` (type: `integer`):

Give up on a single feed request after this many seconds.

## `token` (type: `string`):

Advanced. The Actor discovers Flashscore's feed signature automatically and falls back to a known value. Set this only if both stop working and you have a current signature.

## `proxyConfiguration` (type: `object`):

Optional. The feed answers plain datacenter requests, so no proxy is needed in normal use.

## Actor input object example

```json
{
  "mode": "matches",
  "days": [
    "0"
  ],
  "status": [],
  "countries": [],
  "matchIds": [],
  "details": [],
  "maxItems": 0,
  "maxConcurrency": 5,
  "timeoutSecs": 30,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

In games mode, one row per game: status, face-off time, competition with country, both teams, final score, the score in each period and overtime, the regulation score, and whether the game was decided in regulation, overtime or a shootout. Games with no data appear with ok=false and are not charged.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "days": [
        "0"
    ],
    "countries": [],
    "matchIds": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("clearfetch/flashscore-hockey-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "days": ["0"],
    "countries": [],
    "matchIds": [],
}

# Run the Actor and wait for it to finish
run = client.actor("clearfetch/flashscore-hockey-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "days": [
    "0"
  ],
  "countries": [],
  "matchIds": []
}' |
apify call clearfetch/flashscore-hockey-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,clearfetch/flashscore-hockey-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/VIZf2hLUcoiPm2ufa/builds/kbS06cczcwdNHcNJJ/openapi.json