Track supply-chain disruptions

Four calls cover disruption watch:

Call	Returns
`GET /v1/events`	Active disruption events, newest first, filterable and paged
`GET /v1/events/{id}`	One event in full
`GET /v1/events/countries`	The countries on the risk map right now: how many events, and the worst severity
`GET /v1/events/shipping`	Port activity per country and ship transits per sea route, against their usual level for this time of year

The event id is the same one Research a part and BOM analysis return in their events, so an agent can open any event it was handed.

List events

import os

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/events",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
    params={"country": "UA", "limit": 2},
)
print(response.json())

const response = await fetch("https://api.partfinder.dev/v1/events?country=UA&limit=2", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});
console.log(await response.json());

curl "https://api.partfinder.dev/v1/events?country=UA&limit=2" \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"

Every filter is optional:

country: ISO 3166-1 alpha-2 code, for example CN.
region: Asia-Pacific, Europe, North America, Middle East, Latin America, Africa or Global. These group supply-chain news, not the UN regions on distributors; to match the two, filter by country.
category: a component category such as semiconductors, bearings or logistics. The full list is on the reference page, and a value outside it answers 400 with the list.
days: only events first recorded in the last 1 to 90 days. Omit it for every active event.
limit (1 to 100, default 50) and cursor: when next_cursor is not null, call again with cursor set to it for the next page.

One event

import os

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/events/1205",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
)
print(response.json())

const response = await fetch("https://api.partfinder.dev/v1/events/1205", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});
console.log(await response.json());

curl "https://api.partfinder.dev/v1/events/1205" \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"

{
  "as_of": "2026-10-01T12:16:43.703Z",
  "summary": "Ukraine Black Sea port attacks disrupt grain logistics in Odesa (high severity, Ukraine).",
  "notice": "Informational only. ...",
  "event": {
    "id": 1205,
    "title": "Ukraine Black Sea port attacks disrupt grain logistics in Odesa",
    "summary": "Military attacks on ports and logistics facilities in Ukraine's Odesa and Mykolaiv regions have crippled grain loading operations, ...",
    "severity": "high",
    "report_status": "confirmed",
    "country": "Ukraine",
    "country_code": "UA",
    "region": "Europe",
    "categories": ["commodities", "logistics"],
    "root_cause": "geopolitical_action",
    "supply_chain_impact": ["logistics_disruption", "shortage"],
    "sourcing_implication": "Attacks on Odesa and Mykolaiv ports hinder Ukrainian grain shipments, prompting buyers of Ukrainian commodities to monitor port availability and consider alternative sources.",
    "recommended_action": "monitor",
    "sourcing_urgency": "critical",
    "regions_exposed": ["Europe", "North America", "Asia-Pacific", "Latin America", "Africa"],
    "lead_time": {
      "text": "as much as 12 days",
      "source": {
        "sentence": "Özdemir said waiting times at the Sulina entrance to the Danube had increased from two or three days to as much as 12 days, adding demurrage costs and making delivery schedules harder to manage.",
        "url": "https://millermagazine.com/en/blog/black-sea-disruption-shifts-grain-trade-focus-from-price-to-reliable-delivery-7046"
      },
      "interpretation": "Reported by millermagazine.com on September 30, 2026 for shipments affected by this event."
    },
    "shipping_check": null,
    "source_urls": ["https://www.livemint.com/market/wheat-falls-as-markets-monitor-black-sea-export-prospects/amp-11790558644308.html"],
    "published_date": "2026-09-28T00:00:00.000Z",
    "first_seen": "2026-09-28T04:46:31.972Z"
  }
}

Shortened. The full field reference is the “Get a disruption event” page in the API Reference tab.

severity is how serious the event is in itself, not its effect on any one of your parts. For that, use Research a part or BOM analysis.
report_status is how firm the reporting is: confirmed, developing, probable, rumor, or risk (a warning about something that has not happened).
lead_time is the added lead time for affected shipments. When a report states one, source carries the sentence and its link, and interpretation says who reported it. When source is null, text is an estimate and interpretation says so. Relay it as an estimate.
shipping_check is port activity in the event’s country during the event’s week, for events about ports or shipping.
source_urls are news reports of the event.

Which countries are hit

import os

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/events/countries",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
)
print(response.json())

const response = await fetch("https://api.partfinder.dev/v1/events/countries", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});
console.log(await response.json());

curl "https://api.partfinder.dev/v1/events/countries" \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"

These are the countries on the risk map on partfinder.dev right now: recent events still unfolding, with how many and their worst_severity, most severe first. It is not every country with an active event: a country absent here can still have active events, so to answer “what is happening in this country”, call GET /v1/events?country=. Open the most severe of a country’s listed events with GET /v1/events/{id} and top_event_id.

Port and sea-route activity

import os

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/events/shipping",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
)
print(response.json())

const response = await fetch("https://api.partfinder.dev/v1/events/shipping", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});
console.log(await response.json());

curl "https://api.partfinder.dev/v1/events/shipping" \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"

Each reading is change_from_normal_percent: how a country’s port calls or a sea route’s ship transits over the latest week compare with their usual level for the same time of year. Negative is below usual (-96 is 96% below), positive above (108 is more than twice the usual traffic). Each reading also carries the last day it covers (through) and a sentence saying the same in words. Both lists run furthest below usual first. A drop at a country’s ports or at a strait delays shipments through it.

Errors

A filter outside its allowed values answers 400 with the allowed values in summary; an unknown event id answers 404 event_not_found. Every code is on the Errors page.

Get Started

Core Concepts

Guides

Integrations

Track supply-chain disruptions

List events

One event

Which countries are hit

Port and sea-route activity

Errors

​List events

​One event

​Which countries are hit

​Port and sea-route activity

​Errors

List events

One event

Which countries are hit

Port and sea-route activity

Errors