Skip to main content
HELPERG

Developers

HELPERG Data API

How the public HELPERG Data API is shaped: the data model, public versus authenticated access, the six public endpoints with parameters and limits, errors, retries, caching and the attribution every response carries.

OpenAPI 3.1 documentCapability matrixSources and licences

The data model, in four records

Calendar event
A scheduled official release: date, time where the source states one, the family it belongs to, and the status the source states. derivedState is what the clock supports and is computed per request; a scheduled time that has passed never becomes RELEASED.
Release
A published value: one vintage of one series for one reference period, with unit, scale, publication and detection time. It exists only when an observation has been verified — never inferred from the calendar.
Observation
The current vintage of a series for a period, with how many times it has been revised. Values are decimal strings to preserve published precision; null is a period the source scheduled and has not yet filled.
Revision
A later vintage that replaced an earlier one. The public release record carries revision.count, isRevision and previousValue; the earlier vintage is never deleted.

There is no forecast, consensus, surprise or market-impact field anywhere in the API. importance is HELPERG editorial methodology and says so on every record.

Public and authenticated access

/api/public/v1/
6 endpoints. No credential. Explicit public record shapes. Bounded windows and pages. Shared-cacheable with a weak ETag. This is the surface the pages on this site use.
/api/v1/
14 endpoints. Serves HELPERG ecosystem products with a credential and a scope; wider windows, full canonical records, vintage histories. Not opened by anything on this site, and not requestable from a browser page.

Both read the same corpus through the same services. The public layer maps records into smaller, allow-listed shapes; a field added to a canonical record does not reach the public until a mapper is changed and a test updated. If you need consumer access, that is an agreement with HELPERG, not a form.

Public endpoints

Base URL https://helperg.com. GET and HEAD only. Unknown query parameters are ignored; the query string may not exceed 2048 bytes.

GET /api/public/v1/economics/calendar

Scheduled official releases, grouped by day

ParameterMeaning
from, toInclusive window. YYYY-MM-DD in tz, or an ISO instant. Defaults: 7 days back to 31 days ahead. At most 93 days.
tzIANA zone. When sent, each event gains local.date, local.time and local.timeZone; UTC values stay.
country, currency, source, releaseComma-separated tokens matching ^[A-Za-z0-9_-]{1,64}$, at most 10 each.
region, importanceClosed enumerations (EA, EU27_2020, G7, G20, OECD, WORLD; HIGH, MEDIUM, LOW, UNCLASSIFIED). Unknown values are refused.
limit, cursorPage size default 50, clamped to 200; opaque cursor from meta.nextCursor.

Shared cache: public, max-age=300, stale-while-revalidate=600, with a weak ETag over the data section.

Example request
curl -sS "https://helperg.com/api/public/v1/economics/calendar?from=2026-10-01&to=2026-10-31&tz=Europe/Berlin&region=EA&limit=50"

GET /api/public/v1/economics/releases

Newest published values per series, merged newest first

ParameterMeaning
seriesComma-separated series slugs, at most 10.
country, regionRestrict to series with that country or region.
perSeriesNewest vintages per series, default 1, clamped to 5.
limit, cursorPage size default 20, clamped to 100.

Shared cache: public, max-age=300, stale-while-revalidate=600, with a weak ETag over the data section.

Example request
curl -sS "https://helperg.com/api/public/v1/economics/releases?region=EA&perSeries=2"

GET /api/public/v1/economics/observations

The published vintages of one series, oldest period first

ParameterMeaning
seriesRequired. A registered series slug; unknown is 404. A registered series with nothing ingested here is 503.
from, toReference-period codes such as 2026-08 or 2026-Q2, compared as strings.
limit, cursorPage size default 100, clamped to 365.

Shared cache: public, max-age=600, stale-while-revalidate=1200, with a weak ETag over the data section.

Example request
curl -sS "https://helperg.com/api/public/v1/economics/observations?series=ea-hicp-yoy&from=2025-01"

GET /api/public/v1/weather/current

Current conditions at a point

ParameterMeaning
lat, lonRequired. Decimal degrees, rounded to 2 decimal places before the provider is asked; the served point is in the body.
altitudeOptional metres, −500 to 9000.
unitsmetric (default) or imperial. Measurement field names change with the unit system.

Shared cache: public, max-age=600, stale-while-revalidate=1200, with a weak ETag over the data section.

Example request
curl -sS "https://helperg.com/api/public/v1/weather/current?lat=50.45&lon=30.52"

GET /api/public/v1/news/events

Official economic news: BLS, Eurostat and ECB publications, newest first

ParameterMeaning
from, toInclusive publication window, YYYY-MM-DD (UTC) or ISO instants. Defaults to the last 366 days; at most 366 days.
source, releaseFamily, series, calendarEventComma-separated slugs or ids, exact, at most 10 each. series and calendarEvent match publications linked to any of them.
country, jurisdiction, currency, topicComma-separated codes (upper-cased) or HELPERG topics, at most 10 each.
state, linkStatus, typeClosed enumerations: PUBLISHED, UPDATED, CORRECTED, WITHDRAWN, UNKNOWN · LINKED, PARTIALLY_LINKED, UNLINKED, AMBIGUOUS · NEWS_RELEASE, STATISTICAL_RELEASE, PRESS_RELEASE, MONETARY_POLICY_DECISION, MONETARY_POLICY_STATEMENT, MONETARY_POLICY_ACCOUNT.
limit, cursorPage size default 20, clamped to 100; opaque cursor from meta.nextCursor, valid within one feed generation.

Shared cache: public, max-age=300, stale-while-revalidate=600, with a weak ETag over the data section.

Example request
curl -sS "https://helperg.com/api/public/v1/news/events?from=2026-09-01&to=2026-09-21&source=eurostat-news-releases&releaseFamily=eurostat-euro-indicators-hicp"

GET /api/public/v1/status

Domain-level status: ok, degraded, unavailable, unknown

ParameterMeaning
—No parameters. One body for every caller.

Shared cache: public, max-age=30, stale-while-revalidate=60, with a weak ETag over the data section.

Example request
curl -sS "https://helperg.com/api/public/v1/status"

Response envelope

Every success is { data, meta }. meta carries the request id, freshness, the sources behind this page of records and their attribution records, paging, and — on the economics routes — dataUpdatedAt and dataStatus (fresh, stale after 3 days without a successful ingestion, or unavailable).

Illustrative envelope (economics calendar)
{
  "data": { "...": "the public record shape for the route" },
  "meta": {
    "requestId": "8f142c37-…",
    "generatedAt": "2026-09-21T12:00:00.000Z",
    "cached": false, "cacheAgeSeconds": 0, "stale": false, "degraded": false,
    "sourceCount": 1, "sources": ["eurostat-release-calendar"],
    "attribution": ["Source: Eurostat."],
    "attributionRecords": [{
      "sourceId": "eurostat-release-calendar", "sourceName": "Eurostat release calendar (euro indicators)",
      "sourceUrl": "https://ec.europa.eu/eurostat/web/main/news/release-calendar",
      "required": true, "text": "Source: Eurostat.",
      "licenseName": "CC BY 4.0 (Commission Decision 2011/833/EU)",
      "licenseUrl": "https://creativecommons.org/licenses/by/4.0/",
      "termsUrl": "https://ec.europa.eu/eurostat/help/copyright-notice",
      "modifiedByHelperg": true
    }],
    "totalMatching": 40, "nextCursor": "bzo1MA", "truncated": false,
    "dataUpdatedAt": "2026-09-21T11:42:24.457Z", "dataStatus": "fresh"
  }
}
Illustrative public calendar event
{
  "id": "evt_94412d5a78011d72f645937adfe28487",
  "title": "Flash estimate inflation euro area",
  "release": { "slug": "eurostat-euro-indicators-flash-hicp", "name": "Flash estimate inflation euro area",
               "publisher": "Eurostat", "officialPageUrl": null },
  "country": null, "region": "EA", "currency": "EUR",
  "referencePeriod": { "kind": "UNKNOWN", "code": "UNKNOWN", "startDate": null, "endDate": null },
  "scheduledDate": "2026-10-02", "scheduledAt": null, "timePrecision": "DATE_ONLY",
  "sourceTimezone": "Europe/Luxembourg",
  "status": "SCHEDULED", "derivedState": "UPCOMING",
  "publication": { "releasedAt": null, "detectedAt": null },
  "importance": { "level": "HIGH", "basis": "HELPERG_TAXONOMY_V1" },
  "source": { "id": "eurostat-release-calendar", "name": "Eurostat release calendar (euro indicators)",
              "url": "https://ec.europa.eu/eurostat/web/main/news/release-calendar" },
  "attribution": { "text": "Source: Eurostat.", "required": true },
  "retrievedAt": "2026-09-21T11:41:45.461Z", "sourceUpdatedAt": null,
  "links": { "seriesSlugs": [], "observations": [],
             "calendar": "/api/public/v1/economics/calendar?release=eurostat-euro-indicators-flash-hicp" }
}

Shapes are normative in the OpenAPI document (PublicCalendarResponse,PublicReleasesResponse, PublicObservationsResponse, PublicWeatherCurrentResponse); the examples above illustrate them and are not recorded responses.

Errors and retries

Every error is { "error": { "code", "message", "requestId", "details"? } } with Cache-Control: no-store. Branch on code; messages are deliberately non-specific and may change.

CodeStatusMeaning and what to do
VALIDATION_FAILED400A parameter is malformed or outside its enumeration. details.parameter names it.
ECONOMICS_RANGE_INVALID400The window is inverted or wider than 93 days.
WEATHER_LOCATION_INVALID400lat, lon or altitude is missing or out of range.
NOT_FOUND404No such series, or no such path.
METHOD_NOT_ALLOWED405Only GET and HEAD are served; the Allow header lists them.
RATE_LIMITED429Too many requests from your client for this route in the current window. Retry-After is set.
SERVICE_UNAVAILABLE503The corpus for this route has never been published on this deployment. Not an empty result — retry later, do not cache as empty.
STORAGE_UNAVAILABLE503The store did not answer. Transient; retry with backoff.
UPSTREAM_UNAVAILABLE / UPSTREAM_TIMEOUT / UPSTREAM_INVALID_PAYLOAD / UPSTREAM_PAYLOAD_TOO_LARGE502–504The weather provider failed and no cached reading could be served. Transient; retry with backoff.
INTERNAL500An unexpected failure; the requestId identifies it in HELPERG's logs. Nothing about the cause is echoed.
Retry guidance
On 429 honour Retry-After. On 503 and 5xx retry with exponential backoff and jitter, starting at a few seconds, and never treat a 503 as an empty dataset. On 400 do not retry the same request. Send If-None-Match with the last ETag: a 304 means your copy of the data is current.
Rate limiting, stated as it is
Requests are counted per route and per client in a fixed window on each serving instance; the counter is not shared across instances and this documentation does not claim that it is. Rely on the cache windows above and on conditional requests rather than on the limit.
Response size
Pages are bounded by limit; a serialised page over 1 MB is truncated and flagged meta.truncated: true with no next cursor. Narrow the window or lower the limit.
Browser access
The endpoints are called same-origin by helperg.com's own pages. Cross-origin browser access is not enabled in this version: call them from a server.

Official economic news: what a record is, and whose words are whose

A record of /api/public/v1/news/events is one official publication of its named publisher: a BLS news release, a Eurostat news release, an ECB press release, monetary policy decision, statement, meeting account or statistical release. HELPERG is not the publisher and does not republish the publication; the full text is at canonicalUrl, on the publisher's site.

Source-provided
title, excerpt, publishedAt, updatedAt, canonicalUrl and language are the publisher's. The excerpt is the short feed summary and exists only where reuse is clearly permitted: BLS (public domain) and Eurostat (CC BY 4.0). ECB records carry null.
HELPERG classification
publicationType, releaseFamily, jurisdictions, countries, currencies, topics, referencePeriod and state are HELPERG's, decided by fixed rules (a BLS program, an ECB URL path, an exact Eurostat title pattern) and never by a model. Every record names the two lists under classification.
Deterministic relationships
related links to calendar events, series, release families and released values exist only where the classified family and an exact date or stated reference period agree; linkEvidence says why each one exists, and linkStatus is AMBIGUOUS when two candidates remained and nothing was chosen. Date proximity alone links nothing.
States and freshness
state is PUBLISHED, UPDATED after a publisher-side change, or UNKNOWN without a publication instant; CORRECTED and WITHDRAWN need an explicit source signal, which no v1 feed carries. meta.dataStatus is stale when no news ingestion has succeeded for three days; the feed is served from a published snapshot, never fetched live.
What is not here
No forecast, consensus, market expectation, sentiment, surprise score, investment view or AI-written summary exists in any field. Speeches, interviews, blog posts and research papers are not ingested.

The credentialed /api/v1/news/events serves the same publications in full (provenance, evidence, versions) to an ecosystem consumer holding news:read; no consumer credential holds it in this release.

Attribution requirements

The data is licensed by its publishers, not by HELPERG. Every response tells you exactly what each source requires in meta.attributionRecords: the credit line (text), whether it is required, the licence name and URL, and modifiedByHelperg, which is true on the calendar and weather surfaces because vocabularies, units and dates are normalised. Display the credit wherever the data appears. Eurostat data is CC BY 4.0; European Central Bank data may be reproduced with the ECB cited as source; U.S. Bureau of Labor Statistics data is a U.S. Government work that still asks to be credited; MET Norway weather is CC BY 4.0. Full detail on the sources page.

Versioning: the public namespace is /api/public/v1; additive fields may appear at any time, and a breaking change would be a new version segment. Error codes are part of the contract; messages are not.