Skip to main content
HELPERG
Set your locationWeather forecast

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, decimal strings, revisions and vintages, values HELPERG computes, official links, errors, retries, rate limits, caching and the attribution every response carries. No forecast, consensus or rating exists in any field.

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 or consensus field anywhere in the API, and no field interprets a value. The importance field on calendar events is legacy editorial metadata kept for compatibility; the public interface no longer presents it.

Public and authenticated access

/api/public/v1/
8 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. Reads only: GET and HEAD everywhere, and POST on the three weather routes as an alternative transport for the same read. Unknown query parameters are ignored; the query string may not exceed 2048 bytes.

Where a parameter travels. HELPERG's own request log carries a route name, a request id, a status and a duration — never a URL, never a parameter, never a body. It cannot make the same promise about the hosting platform: a request path and its query string are part of the request metadata Vercel records. A caller who does not want a coordinate or a search term in that metadata can send the same parameters as a JSON body over POST on /weather/current, /weather/forecast and /weather/places. The GET forms are unchanged and remain the right shape for a cacheable public read; a POST is answeredCache-Control: no-store, because an intermediary keying on the URL alone would otherwise hold one caller's answer under a URL every caller shares.

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.
qSearch text, at most 80 characters: a case-insensitive substring of the event title or the release family name.
country, currency, source, releaseComma-separated tokens matching ^[A-Za-z0-9_-]{1,64}$, at most 10 each.
region, statusClosed enumerations (EA, EU27_2020, G7, G20, OECD, WORLD; the source statuses SCHEDULED … UNKNOWN). Unknown values are refused.
importanceAccepted for compatibility only: legacy editorial metadata (HIGH, MEDIUM, LOW, UNCLASSIFIED) that the public calendar no longer presents or filters by. It measures nothing and predicts nothing.
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 · POST /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"
The same read, with the parameters in a body
curl -sS -X POST "https://helperg.com/api/public/v1/weather/current" \
  -H 'Content-Type: application/json' \
  -d '{"lat":50.45,"lon":30.52}'

GET · POST /api/public/v1/weather/forecast

Weather forecast for a point: hours and days, from the same service as the current-conditions route

ParameterMeaning
lat, lonRequired. Decimal degrees, rounded to 2 decimal places before the provider is asked.
altitudeOptional metres, −500 to 9000.
tzIANA zone the daily records are assembled in. Defaults to UTC.
unitsmetric (default) or imperial.
hours, daysPage sizes, clamped rather than refused. The provider decides the real horizon: fewer days than requested is its answer, not a failure.

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

Example request
curl -sS "https://helperg.com/api/public/v1/weather/forecast?lat=50.45&lon=30.52&hours=24&days=7"
The same read, with the parameters in a body
curl -sS -X POST "https://helperg.com/api/public/v1/weather/forecast" \
  -H 'Content-Type: application/json' \
  -d '{"lat":50.45,"lon":30.52,"hours":24,"days":7}'

GET · POST /api/public/v1/weather/places

Find a place by name (optional capability: 200 with an empty list where no provider is configured)

ParameterMeaning
qThe place name. Shorter than two characters is answered without calling any provider.
limitResult ceiling, clamped to a small maximum.

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/weather/places?q=Kyiv"
The same read, with the parameters in a body
curl -sS -X POST "https://helperg.com/api/public/v1/weather/places" \
  -H 'Content-Type: application/json' \
  -d '{"q":"Kyiv"}'

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 — and whether the corpus is in durable storage

ParameterMeaning
—No parameters. One body for every caller. Documented in the OpenAPI document as PublicStatusResponse.

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, "confirmed": false, "evidence": [], "officialPublication": 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" },
  "sourceLink": { "url": "https://ec.europa.eu/eurostat/web/main/news/release-calendar", "type": "calendar",
                  "label": "The publisher's release calendar (not event-specific)", "publisher": "Eurostat (Statistical Office of the European Union)",
                  "sourceId": "eurostat-release-calendar", "retrievedAt": "2026-09-21T11:41:45.461Z", "attribution": "Source: Eurostat." },
  "values": { "headlineSeries": null, "availability": "NO_SERIES_MAPPED", "referencePeriod": null, "periodSource": null, "actual": null, "previous": null },
  "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, PublicNewsEventsResponse,PublicWeatherCurrentResponse, PublicStatusResponse); the examples above illustrate them and are not recorded responses. Every public route is documented there, whatever its domain.

Values, revisions and what HELPERG computes

Decimal strings
Every published value is a decimal string — "3.4", "-0.6", "7271" — never a JSON number, so the publisher's precision survives the round trip; parse with a decimal type, not a float. unitCode names the unit and scale is the power of ten already applied: value "7271" with unit PERSONS and scale 3 is 7 271 thousand persons. null is a period the source scheduled and has not yet filled; it is never zero.
Publication status
publicationStatus is what the source stated for that vintage — NORMAL, or PRELIMINARY and the like where the publisher flags it. The pages show the word only when it is not the ordinary one.
Revisions and vintages
A revision is a later vintage of the same period; the earlier vintage is kept, never deleted. A release carries revision.count (vintages beyond the first), revision.isRevision and revision.previousValue (the value this vintage replaced); the observations endpoint lists every vintage. previous on a release is a different thing: the newest earlier period of the same series that carries a value, so a reader can compare two periods without a second request.
Values HELPERG computes
Most values are the publisher's own figure, copied through. Where an official interface publishes the inputs and not the headline — the BLS Public Data API supplies an index or level and no calculations to an anonymous caller — HELPERG derives the change the agency itself prints, in exact decimal arithmetic. Such a value carries derived: the formula and the publisher's inputs with their periods, so it can be recomputed rather than trusted. derived is null on every value the publisher printed. A computed value is HELPERG's output and is never presented as the publisher's publication.
Official links on every record
A calendar event carries sourceLink — the most specific official page HELPERG can prove, typed event (the publisher's release notice), release (the family's page), series (the publisher's dataset page) or calendar (the publisher's calendar) — and release.officialPageUrl. A series carries officialSeriesUrl. A publication carries canonicalUrl and rightsUrl. Every URL is on the publisher's own host; HELPERG links no mirror and no aggregator.
What never appears
No forecast, consensus, estimate, surprise, sentiment, market-impact or rating field exists in any public record, and none will be added under this namespace. importance on calendar events is legacy editorial metadata kept for compatibility; it measures nothing, and the public pages do not present it.

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. A refused request answers 429 with Retry-After and a RATE_LIMITED code; the pages on this site never retry automatically, and neither should a client without backoff. 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, estimate, rating 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 wherever HELPERG normalised vocabularies, units, dates or links — the calendar, news and weather surfaces — and every value HELPERG computed carries the disclosure on the record itself. 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.