API · ECI Monitor

Scope

The API is read-oriented. It exposes selected initiative metadata, snapshot history, cached initiative logos, and a refresh endpoint that may run the tracker only when the cached source data is due for an update.

All timestamps returned by the API are Unix seconds in UTC.

The API is intended for lightweight reuse and transparency, not as a guaranteed long-term public contract. Field names may evolve while the project is still being developed.

Where the data comes from

Raw initiative details and signature totals come from the official European Citizens’ Initiative public register. ECI Monitor does not collect signatures and is not the official signing system.

For selected initiatives, the tracker periodically checks the official source. When the source reports a newer update time, ECI Monitor stores a local snapshot of the totals and country breakdown.

The displayed charts, short-term rates, targets, ETAs, and country momentum lists are derived by ECI Monitor from those stored snapshots. They should be read as estimates or analysis, not as official ECI metrics.

National threshold values are the official ECI country thresholds used to determine whether an initiative has met the minimum spread requirement across EU countries.

API responses are derived from public ECI register data. See Legal for source attribution and reuse notes.

List tracked initiatives

Always returns an initiatives array. Without ids, it contains all initiatives selected by the site administrator. With ids, it contains only the requested initiatives.

The fields parameter is orthogonal to filtering. Use it to attach heavier subobjects to every returned initiative.

GET /api.php?action=initiatives
GET /api.php?action=initiatives&fields=details
GET /api.php?action=initiatives&ids=2025-000005&fields=details,state

List fields

initiatives[] Array of selected initiative objects.

id Local initiative identifier used in URLs and API calls, such as 2025-000005.

registerPath Path fragment used by the official ECI register for the initiative.

selected Whether the site administrator has enabled the initiative for public tracking.

language Default language configured for the initiative.

refreshIntervalMinutes Tracker refresh interval for this initiative in minutes. Falls back to the server default when not configured explicitly.

social Administrator-maintained social sharing metadata for this initiative.

pitch Localized activist sentence used by nudge and share text, keyed by language code.

	`<language-code>`	One localized campaign pitch.

card Localized share-card metadata used for Open Graph and Twitter/X previews, keyed by language code.

<language-code> One localized share-card version.

	`title`	Short share title. Keep it under about 70 characters for broad social compatibility.
	`description`	Short share description. Keep it under about 200 characters for broad social compatibility.

tags[] Optional administrator-defined tags.

Optional fields

initiatives[] Array of selected initiative objects.

details Cached official initiative metadata, included when details is requested.

comRegNum Official registration number, such as ECI(2025)000005.

localizations Localized initiative content keyed by language code.

<language-code> One localized version of the initiative.

	`title`	Localized initiative title.
	`objectives`	Localized initiative objectives as plain text.
	`website`	Localized campaign website URL when provided by the official source.
	`supportLink`	Localized official signing URL when provided by the official source.

logo Official initiative logo metadata when available.

	`id`	Official ECI logo id used by the logo endpoint.
	`name`	Original logo file name when provided by the official source.
	`size`	Original logo file size when provided by the official source.

thresholds National ECI threshold values used by this tracker, keyed by country code.

	`note`	Optional public note explaining the threshold choice when needed.
	`<country-code>`	National threshold value for that country.

state Last known tracker state for the initiative, included when state is requested.

	`lastAttemptAt`	Last time the tracker tried to refresh the initiative, as Unix seconds in UTC.
	`lastSuccessAt`	Last successful tracker refresh, as Unix seconds in UTC.
	`lastSourceUpdatedAt`	Newest official source update known to ECI Monitor, as Unix seconds in UTC.
	`lastErrorAt`	Last tracker failure time, as Unix seconds in UTC, if a failure occurred.
	`lastError`	Last tracker error if one occurred.
	`consecutiveErrors`	Number of failed tracker attempts since the last successful refresh.

Snapshot stream

Returns initiative snapshots as newline-delimited JSON. The browser uses this stream to build the charts client-side.

Use the after parameter to request only snapshots newer than a known source update timestamp. Timestamps are Unix seconds in UTC. When a version is supplied, immutable cache headers and an ETag are emitted for that stream URL.

GET /api.php?action=snapshots&id=2025-000005
GET /api.php?action=snapshots&id=2025-000005&after=1776420000&version=1776421200

Fields

sourceUpdatedAt Official source update time as Unix seconds in UTC.

fetchedAt Time when ECI Monitor fetched and stored the snapshot, as Unix seconds in UTC.

total Initiative-wide signature total used by the app.

countryTotals Country signature totals keyed by two-letter country code.

	`<country-code>`	Signatures for that country at this snapshot.

Logo images

Returns a cached logo for the initiative. PNG is the fallback format. Add format=webp to request a WebP version when the server can encode it. The default variant is trimmed for display in the page. The social variant is padded to a Facebook-friendly 1.91:1 PNG image for link previews.

The logo query value is a cache buster based on the ECI logo id. The optional v query value is also a cache buster and is ignored by the API logic.

GET /api.php?action=initiative-logo&id=2025-000005&logo=9055
GET /api.php?action=initiative-logo&id=2025-000005&logo=9055&format=webp&v=php-244
GET /api.php?action=initiative-logo&id=2025-000005&logo=9055&variant=social&v=php-244

Refresh

Checks whether the initiative is due for a tracker run. If the cached data is still fresh, it returns the cached state without contacting the official ECI source. If the data is due, one request obtains the per-initiative tracker lock and performs the refresh.

If another request is already refreshing the same initiative, the response reports that a refresh is already running instead of starting a second job.

GET /api.php?action=refresh&id=2025-000005

Fields

	`status`	What happened, for example cached data was used, a refresh ran, or another refresh was already running.
	`reason`	Machine-readable reason when no refresh was run or when an error-like condition occurred.
	`refreshIntervalMinutes`	Tracker refresh interval for this initiative in minutes.
	`snapshotAppended`	Whether a new local snapshot was stored during the refresh, when applicable.
	`lastSourceUpdatedAt`	Newest official source update known after the refresh decision, as Unix seconds in UTC.
	`checkedAt`	Time when the refresh decision was made or the source was checked.