# Japan Bear Sightings (クマ出没情報) - Open Data Scraper (`jpopendata/japan-bear-sightings`) Actor

Bear sighting, trace and injury reports in Japan (ツキノワグマ/ヒグマ) from prefectural and city open data: Akita KumaDAS, Ishikawa, Sapporo, Kyoto, Kamisunagawa, Yamaguchi. Date, place, coordinates, type, cubs. CC BY / PDL sources only. Unofficial; not affiliated with any publisher.

- **URL**: https://apify.com/jpopendata/japan-bear-sightings.md
- **Developed by:** [JP Open Data](https://apify.com/jpopendata) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 results

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Japan Bear Sightings (クマ出没情報) — Open Data Scraper

Bear sighting, trace and human-injury reports from Japan — **ツキノワグマ (Asian black bear)** and **ヒグマ (brown bear)** — collected from the open-data catalogues of prefectures and cities and delivered in **one English schema**: date and time, prefecture, municipality, district (大字 level), latitude/longitude rounded to about 100 m, report type, species, head count, cubs, sex, environment and body length.

Only datasets whose licence allows **commercial reuse** are read (CC BY 4.0 or PDL1.0). Every record carries the credit line its publisher asks for.

Good for: news and data journalism, municipal and outdoor-safety dashboards, tourism and trail operators, insurers, and wildlife researchers who need several prefectures in one table instead of six differently shaped CSV files.

### What it does

- Reads six official open datasets (see the table below) — no maps, no screen scraping.
- Normalizes Japanese era dates (令和8年1月4日, R4.3.3), times (7時00分頃), head counts (成獣１頭), Shift_JIS files and the different column layouts into one schema.
- Classifies each report as **sighting (目撃)**, **trace (痕跡)**, **injury (人身被害)**, **capture (捕獲・駆除)** or **other** — from the publisher's own category column where there is one (Akita, Ishikawa 2019-2024), otherwise from keywords (`typeBasis` tells you which).
- Cuts places to district level (大字 / 町丁目). House numbers, postal codes, building and shop names are removed, and coordinates are rounded to 3 decimal places (about 100 m).
- Filters by date window, prefecture, municipality and report type; newest first.

### Sources and licences

| `sourceId` | Publisher | Dataset | Coverage (as of October 2026) | Updates | Licence |
|---|---|---|---|---|---|
| `akita` | 秋田県 Akita Prefecture | 【秋田県】ツキノワグマ等情報マップシステム『クマダス』データ (KumaDAS) | April 2022 → | monthly, to the end of the previous month | CC BY 4.0 |
| `ishikawa` | 石川県 Ishikawa Prefecture | 石川県クマ出没データ | 2019 → June 2025 | irregular | いしかわオープンデータカタログ terms (commercial use allowed, CC BY 4.0 compatible) |
| `sapporo` | 札幌市 City of Sapporo (Hokkaido) | 札幌市内のヒグマ出没情報 | 2017 → November 2025 | one file per year, after the season | CC BY 4.0 |
| `kyoto` | 京都府 Kyoto Prefecture | 【京都府】クマ目撃情報 | fiscal years 2009-2018 | closed archive | CC BY 4.0 |
| `kamisunagawa` | 上砂川町 Town of Kamisunagawa (Hokkaido) | ヒグマ出没マップ (one per fiscal year) | April 2024 → | during the season | CC BY 4.0 |
| `yamaguchi` | 山口県 Yamaguchi Prefecture | 熊の目撃情報（山口県警察認知のもの） (one per year) | 2023 → | during the year | PDL1.0 (CC BY 4.0 compatible) |

Each record's `license` field holds the exact credit line required by that publisher's terms (for example 「出典：山口県オープンデータカタログサイト（URL）、PDL1.0（URL）。「熊の目撃情報２０２６（山口県警察認知のもの）」（山口県）（URL）を加工して作成」), the licence URL, a note that the data was edited by this tool, and the not-affiliated statement. **When you publish the data, keep that credit line** — it is a condition of the licences.

Prefectures not listed (Iwate, Miyagi, Yamagata, Fukushima, Niigata, Toyama, Nagano, ...) publish maps or PDFs without a commercial-use licence, or forbid reproduction; they are deliberately not included.

### Quick start

Verified input — the last 30 days from all six sources, newest 200 reports (finishes in seconds; 7 catalogue requests):

```json
{
    "daysBack": 30,
    "maxItems": 200
}
```

Running with `{}` does exactly the same. More examples:

- All of Akita's 2025 autumn season: `{"sources": ["akita"], "dateFrom": "2025-09-01", "dateTo": "2025-11-30", "maxItems": 20000}`
- Human-injury reports, all history, all sources: `{"daysBack": 0, "types": ["injury"], "maxItems": 5000}`
- One city: `{"municipalities": ["秋田市"], "daysBack": 365, "maxItems": 5000}`
- Hokkaido brown bears (Sapporo + Kamisunagawa): `{"prefectures": ["Hokkaido"], "daysBack": 0, "maxItems": 5000}`

### Input

| Field | Default | Meaning |
|---|---|---|
| `daysBack` | 30 | Reports dated on or after today (Japan time) minus this many days. `0` = all history. Ignored when `dateFrom` is set. |
| `dateFrom`, `dateTo` | empty | Date window, `YYYY-MM-DD` (also `2025/4/1`, `20250401`, `2025年4月1日`, `令和7年4月1日`, or `2025-04` for a whole month). |
| `sources` | all six | `akita`, `ishikawa`, `sapporo`, `kyoto`, `kamisunagawa`, `yamaguchi` (Japanese names such as `秋田` work too). |
| `prefectures` | all | `Akita`, `Ishikawa`, `Hokkaido`, `Kyoto`, `Yamaguchi` — English, Japanese (`秋田県`) or JIS code (`05`). |
| `municipalities` | all | Japanese names as the publishers write them: `秋田市`, `鹿角市`, `加賀市`, `山口市`, `札幌市` (all wards) or `札幌市南区`. The 市/町/村 ending is optional. |
| `types` | all | `sighting`, `trace`, `injury`, `capture`, `other` (or 目撃, 痕跡, 人身被害, 捕獲, その他). |
| `maxItems` | 200 | Maximum records stored, newest first. |
| `maxRequests` | 80 | Hard limit on catalogue requests per run. A full-history run of all sources needs about 30. |
| `proxyConfiguration` | none | Optional proxy for the catalogues that answer Apify directly. |
| `residentialProxyConfiguration` | Apify RESIDENTIAL, JP | Used only for the Ishikawa catalogue, which refuses Apify's datacenter IPs (HTTP 403, checked 2026-10-13). Billed by Apify as proxy traffic (a catalogue page is about 50 KB; the full Ishikawa history about 1 MB). Without it, Ishikawa is reported as refused and the other sources still run. |

### Output

One record per report. Example (Akita, 28 September 2026 — a mother bear with cubs):

```json
{
    "sightingId": "akita:28046",
    "sourceId": "akita",
    "publisher": "秋田県",
    "datasetTitle": "【秋田県】ツキノワグマ等情報マップシステム『クマダス』データ",
    "datasetUrl": "https://ckan.pref.akita.lg.jp/dataset/050008_shizenhogoka_003",
    "licenseId": "CC-BY-4.0",
    "sourceRecordId": "28046",
    "date": "2026-09-28",
    "yearMonth": "2026-09",
    "time": "11:30",
    "dateTime": "2026-09-28T11:30:00+09:00",
    "prefecture": "秋田県",
    "prefectureEn": "Akita",
    "prefectureCode": "05",
    "municipality": "北秋田市",
    "ward": null,
    "locality": "前山萩岱",
    "latitude": 40.221,
    "longitude": 140.323,
    "type": "sighting",
    "typeJa": "目撃",
    "typeBasis": "category",
    "typeLabelJa": "目撃",
    "species": "asian_black_bear",
    "speciesJa": "ツキノワグマ",
    "count": 3,
    "adults": null,
    "cubs": null,
    "ageClass": "mother_with_cubs",
    "sex": null,
    "environment": null,
    "bodyLengthCm": null,
    "source": "秋田県オープンデータカタログサイト — 【秋田県】ツキノワグマ等情報マップシステム『クマダス』データ",
    "sourceUrl": "https://ckan.pref.akita.lg.jp/dataset/050008_shizenhogoka_003",
    "license": "この「データベース」は以下の著作物を改変して利用しています。「【秋田県】ツキノワグマ等情報マップシステム『クマダス』データ」、秋田県、クリエイティブ・コモンズ・ライセンス 表示4.0（https://creativecommons.org/licenses/by/4.0/legalcode.ja） — Licence: CC BY 4.0 ... Unofficial — not affiliated with or endorsed by 秋田県 (Akita Prefecture) or the catalogue operator.",
    "retrievedAt": "2026-10-13T00:00:00.000Z"
}
```

#### Field reference

| Field | Notes |
|---|---|
| `date`, `time`, `dateTime` | Japan time. `time` is null when not published. A few Yamaguchi reports give only a month (令和6年7月中旬): `date` is null and `yearMonth` is set. |
| `municipality`, `ward`, `locality` | `ward` only for designated cities (札幌市 南区, 京都市 左京区). `locality` is the 大字 / 町丁目 name, or null when the publisher's text had no clean place name. |
| `latitude`, `longitude` | WGS84, rounded to 3 decimal places (about 100 m). The published points are often precise to about 1 m; the rounded point shows the area of the report, not a single house or garden. |
| `type`, `typeJa`, `typeBasis` | `typeBasis`: `category` = the publisher's own category column; `text` = keywords in the publisher's remark (the remark itself is not output); `dataset` = the dataset's own label (e.g. Kyoto's 目撃情報). |
| `typeLabelJa` | The publisher's category label when it is a fixed value (e.g. 痕跡(食害)), else null. |
| `count`, `adults`, `cubs` | Head count as published; `adults` / `cubs` only where the publisher counts them separately (Kyoto). |
| `ageClass` | `adult`, `cub`, `mother_with_cubs` (親子) or null. |
| `sex` | The bear's sex, `male` / `female`, where published (Akita), else null. Always null on injury reports, so it cannot be mistaken for the injured person's sex. |
| `environment` | `residential`, `road`, `farmland`, `forest`, `river`, `other` (Kyoto's 環境区分 and Yamaguchi's location note), else null. |
| `bodyLengthCm` | Body length where stated (Yamaguchi's column; "70センチのクマ" style remarks), else null. |

The key-value store record `RUN_SUMMARY` lists, per source, the files read, reports parsed and matched, duplicates removed, the **newest report date available** and any stop reason.

### Empty results?

- **Publishing delays.** Akita publishes monthly (data up to the end of the previous month), Sapporo once a year after the season, Ishikawa irregularly (latest June 2025), Kyoto is a 2009-2018 archive. A short `daysBack` can therefore return nothing for some sources — `RUN_SUMMARY.sources[].newestReport` shows how far each one goes. Use `daysBack: 0` or `dateFrom` for history.
- **Municipality spelling.** Use the Japanese name as published (`鹿角市`, not `Kazuno`).
- **Prefecture without a source.** Only Akita, Ishikawa, Hokkaido (Sapporo, Kamisunagawa), Kyoto and Yamaguchi are covered; others give a warning and no records.
- A run with no matching report ends successfully with 0 records and a warning.

### Common input mistakes

| You entered | Use instead |
|---|---|
| `"prefectures": ["Sapporo"]` | `"prefectures": ["Hokkaido"]` or `"municipalities": ["札幌市"]` |
| `"municipalities": ["Akita"]` | `"municipalities": ["秋田市"]` |
| `"dateFrom": "01/09/2025"` | `"dateFrom": "2025-09-01"` |
| `"types": ["attack"]` | `"types": ["injury"]` |
| `"sources": ["kumadas.net"]` | `"sources": ["akita"]` |

### Privacy

- **No free-text remarks.** The publishers' remark and status columns (目撃時の状況, 備考, 状況, 特記事項 ...) can describe reporters or injured people; they are read only to classify the report and are never output.
- **No house numbers, no exact points.** Places are cut to district level; postal codes, 番地, building, shop and facility names are removed (a shop name can be a sole trader's name). Coordinates are rounded to about 100 m.
- **Nothing about people.** No reporter, victim, police station or follow-up action fields. Injury reports keep only when and where (district and the rounded point) and facts about the bear; the bear's `sex` is left empty on them.

### How it accesses the sources

- Official open-data catalogues only: dataset pages, the catalogue API where the site's robots.txt allows it, and the published CSV files. Every request is checked against the site's robots.txt first.
- One request at a time per catalogue, 10 seconds apart on the catalogues that ask for it (Akita, Ishikawa, Sapporo), 2 seconds elsewhere; a hard request limit per run; no redirects followed; no evasion. A source that refuses or changes its layout is reported in `RUN_SUMMARY` and the others still deliver.

### Not for emergencies

This is **not a real-time alert service**. The publishers update with a delay of days to months, and absence of a report does not mean absence of bears. For safety decisions, follow the official alerts of the prefecture and municipality (クマ出没警報・注意報) and local news.

### Disclaimer

**Unofficial** — this Actor is not affiliated with or endorsed by 秋田県, 石川県, 札幌市, 京都府, 上砂川町, 山口県 or the catalogue operators (BODIK / 九州先端科学技術研究所 and others). It only reads public open data. The data is provided as published, without any guarantee of completeness or accuracy, and has been edited (renamed, normalized, coordinates rounded, filtered) by this tool. You are responsible for complying with each dataset's licence and terms — in particular for keeping the credit line in the `license` field when you redistribute the data — and with privacy laws that apply to you (GDPR, Japan's APPI). If you are a publisher and want a dataset removed, please contact us through Apify.

# Actor input Schema

## `daysBack` (type: `integer`):

Reports dated on or after today (Japan time) minus this many days. 0 = no lower limit (all history: Kyoto from 2009, Sapporo from 2017, Akita from April 2022 ...). Ignored when "Date from" is set. Note: publishers update with a delay — Akita monthly (data to the end of the previous month), Sapporo once a year, Yamaguchi and Kamisunagawa during the season.

## `dateFrom` (type: `string`):

Optional. First day, YYYY-MM-DD, e.g. "2025-04-01". Also accepted: 2025/4/1, 20250401, 2025年4月1日, 令和7年4月1日, and "2025-04" for a whole month. Overrides Days back.

## `dateTo` (type: `string`):

Optional. Last day, YYYY-MM-DD, e.g. "2025-11-30" ("2025-11" = to the end of November). Empty = today.

## `sources` (type: `array`):

Which publishers to read, one per line: akita (秋田県 クマダス, monthly, from 2022-04), ishikawa (石川県, 2019-2025), sapporo (札幌市, one file per year, from 2017), kyoto (京都府, archive FY2009-2018), kamisunagawa (上砂川町, from FY2024), yamaguchi (山口県 police reports, from 2023). Japanese names work too (秋田, 札幌 ...). Empty = all six.

## `prefectures` (type: `array`):

Optional. Keep only these prefectures, one per line: Akita, Ishikawa, Hokkaido, Kyoto, Yamaguchi (English or Japanese names such as 秋田県, or JIS codes such as 05). Other prefectures are valid input but have no source in this Actor yet (a warning says so). Empty = all.

## `municipalities` (type: `array`):

Optional. Keep only these cities / towns, in Japanese as the publishers write them, one per line: "秋田市", "鹿角市", "北秋田市", "加賀市", "山口市", "札幌市" (all wards) or "札幌市南区" (one ward). The 市/町/村 ending is optional ("秋田" = "秋田市"). Romanized names match nothing. Empty = all.

## `types` (type: `array`):

Optional. Keep only these report types, one per line: sighting (目撃), trace (痕跡: droppings, footprints, feeding or claw marks), injury (人身被害: a person hurt), capture (捕獲・駆除: caught or culled), other (e.g. only heard). Japanese labels work too. Empty = all.

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

Maximum records stored, newest first, all sources together (1..200000). Volumes swing with the season: Akita alone published 5,810 reports for October 2025 but about 100 for September 2026. Each stored record is charged.

## `maxRequests` (type: `integer`):

Hard limit on HTTP requests to the catalogues for the whole run (5..300). A full-history run of all six sources needs about 30 (one CSV per year per source plus one catalogue page per source); the Quick start needs about 7.

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

Optional proxy for the catalogues that answer Apify's servers directly. Default: no proxy. If you set one, one sticky session (one IP) is kept per catalogue for the whole run, never rotation.

## `residentialProxyConfiguration` (type: `object`):

Proxy for the Ishikawa open-data catalogue (いしかわオープンデータカタログ), which refuses Apify's datacenter IPs (HTTP 403, checked 2026-10-13). Default: Apify RESIDENTIAL proxies, country JP — billed by Apify as proxy traffic (one catalogue page is about 50 KB, a CSV 20-550 KB). One sticky session for the whole run; only a refused first request is retried once on a fresh session. Without it, the Ishikawa source is reported as refused and the other sources still run.

## Actor input object example

```json
{
  "daysBack": 30,
  "dateFrom": "",
  "dateTo": "",
  "sources": [
    "akita",
    "ishikawa",
    "sapporo",
    "kyoto",
    "kamisunagawa",
    "yamaguchi"
  ],
  "prefectures": [],
  "municipalities": [],
  "types": [],
  "maxItems": 200,
  "maxRequests": 80,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "residentialProxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "JP"
  }
}
```

# Actor output Schema

## `records` (type: `string`):

One record per report with source attribution (source, sourceUrl, license, retrievedAt) on every item.

## `summary` (type: `string`):

Per-source files read, reports parsed, newest report date and stop reasons.

# 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 = {
    "daysBack": 30,
    "dateFrom": "",
    "dateTo": "",
    "sources": [
        "akita",
        "ishikawa",
        "sapporo",
        "kyoto",
        "kamisunagawa",
        "yamaguchi"
    ],
    "prefectures": [],
    "municipalities": [],
    "types": [],
    "maxItems": 200,
    "maxRequests": 80,
    "proxyConfiguration": {
        "useApifyProxy": false
    },
    "residentialProxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "JP"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("jpopendata/japan-bear-sightings").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 = {
    "daysBack": 30,
    "dateFrom": "",
    "dateTo": "",
    "sources": [
        "akita",
        "ishikawa",
        "sapporo",
        "kyoto",
        "kamisunagawa",
        "yamaguchi",
    ],
    "prefectures": [],
    "municipalities": [],
    "types": [],
    "maxItems": 200,
    "maxRequests": 80,
    "proxyConfiguration": { "useApifyProxy": False },
    "residentialProxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "JP",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("jpopendata/japan-bear-sightings").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 '{
  "daysBack": 30,
  "dateFrom": "",
  "dateTo": "",
  "sources": [
    "akita",
    "ishikawa",
    "sapporo",
    "kyoto",
    "kamisunagawa",
    "yamaguchi"
  ],
  "prefectures": [],
  "municipalities": [],
  "types": [],
  "maxItems": 200,
  "maxRequests": 80,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "residentialProxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "JP"
  }
}' |
apify call jpopendata/japan-bear-sightings --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jpopendata/japan-bear-sightings"
        }
    }
}
```

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/2YyBdsjdotixEyV2k/builds/KzB84Z7scj9UKEjlo/openapi.json