Skip to main content
Glama

Poland Car & EV Registrations API – CEPiK Official Stats

polish-vehicle-registrations-cepik
Read-onlyIdempotent

Returns monthly vehicle registration counts from CEPiK, grouped by brand, model, fuel, powertrain or region and filtered by vehicle type, fuel and date range for fleet and EV adoption statistics.

Instructions

Returns monthly vehicle registration counts from the official CEPiK open data API, grouped by brand, model, fuel, powertrain, origin, production year or county and filtered by vehicle type, fuel, origin, voivodeship and month range (at most 60 months per run); aggregates only, no VINs or owners. Defaults are electric passenger cars in Mazowieckie for the last complete month; all of Poland can take several minutes when CEPiK is busy. Use it for fleet and EV adoption statistics; for charging infrastructure use polish-ev-charging-stations-eipa. Read-only: it only queries the public source and never writes to the registry; onlyNew merely keeps a stateKey memory in your own Apify account. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/polish-vehicle-registrations-cepik on your Apify account, billed pay-per-event per delivered item plus any Apify platform usage; the server waits up to 300 s for the run and returns JSON {items, truncated} with at most maxItems (max 100) items and 256 KiB.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "polish-vehicle-registrations-cepik"
  }
}

Input Schema

NameRequiredDescriptionDefault
topNNoKeep only the N largest groups per month and area. 0 = all groups.
brandNoOptional exact make as registered, e.g. TOYOTA (case does not matter).
modelNoOptional exact model as registered, e.g. MODEL Y.
originNoCount only vehicles of this origin, e.g. new cars bought in Poland or used imports.ANY
groupByNoColumns to count by. Empty = one total per month and area (fastest: counts come straight from the API without reading records).
monthToNoLast month, YYYY-MM. Months are reported newest first. At most 60 months per run.
onlyNewNoSkip rows already delivered by an earlier run with the same state key and the same count. Useful for schedules.
fuelTypeNoCount only this primary fuel. Hybrids are registered with petrol or diesel as primary fuel; use groupBy powertrain to see them.ELECTRIC
maxItemsNoHard cap of dataset rows (each row is one charged event).
stateKeyNoName of the remembered set of delivered rows (letters, digits, - and _).
areaLevelNoReport one total for Poland (or for the selected voivodeships together) or one block of rows per voivodeship.POLAND
dateBasisNoWhich registration date puts a vehicle in a month.FIRST_REGISTRATION_IN_POLAND
monthFromNoFirst month, YYYY-MM (e.g. 2026-01). Leave both months empty for the last complete month. With only From, the range runs to the current month (marked partialPeriod).
vehicleTypeNoCount only this vehicle type (exact CEPiK value).PASSENGER_CAR
voivodeshipsNoDefault: 14 MAZOWIECKIE. Clear the field (empty list) for all of Poland (all 16 voivodeships plus records with no voivodeship, code XX); all of Poland reads 17 voivodeships and takes several minutes when CEPiK is busy.
cacheTtlHoursNoReuse breakdowns that needed more than 1,000 records and were read by an earlier run of yours within this many hours. 0 = always ask CEPiK.
minRegistrationsNoSkip groups smaller than this.
maxRequestsPerSecondNoPoliteness limit towards api.cepik.gov.pl. Requests are always sent one at a time.
onlyCurrentlyRegisteredNoCEPiK's default: count only vehicles that are registered today. Turn off to include vehicles deregistered since.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnly/idempotent/destructive/openWorld, but the description goes well beyond: costs (paid Apify run, pay-per-event billing plus platform usage), required APIFY_TOKEN env var, 300 s server wait, the {items, truncated} return shape with maxItems 100 and 256 KiB caps, the 60-month limit, and the fact that onlyNew only stores a stateKey in the caller's own account. That is unusually complete disclosure for a hosted-actor wrapper.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what it returns and how, then usage routing, then cost/latency/return-shape caveats. It is a dense single paragraph and billing details are somewhat packed together, but no sentence is padding and each adds decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 19-parameter, zero-required tool with no output schema, the description supplies the return envelope, size caps, latency expectations, auth requirement, billing model and default behavior. An agent can call this correctly and predict cost/latency without opening anything else.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it explains the defaults (electric passenger cars, Mazowieckie, last complete month), that an empty groupBy is fastest because counts come straight from the API, and the semantics of the month range. It does not re-explain every parameter, but the ones that drive cost and runtime are covered.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (monthly vehicle registration counts from CEPiK open data), enumerates the grouping and filter dimensions, and explicitly names the sibling tool for charging infrastructure so the agent can tell them apart. Defaults are also stated, which sharpens the mental model.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit use case ('fleet and EV adoption statistics') and an explicit alternative with the condition that selects it ('for charging infrastructure use polish-ev-charging-stations-eipa'). It also warns that all-of-Poland queries can take several minutes, letting the agent choose scope deliberately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.