API documentation

Pull station-level and aggregate fuel-price data with clear billing rules.

The commercial API is designed for authenticated requests by customer account. Buyers can query current station rows, station history, or aggregate market averages by brand, location, fuel type, and time window.

View pricing Contact sales

AuthenticationEvery commercial pull uses a customer API key tied to an organization and subscription.

QuotaSuccessful billable data responses count against the included monthly request package.

ProtectionUnavailable coverage, invalid parameters, and unavailable history should fail before billing.

Supported pull patterns

The API is organized around the questions customers usually ask. Detailed field definitions and response contracts are shared privately after qualification.

Row-level

Station data by station or filtered market.

Use station-level pulls when you need current observations for a known station, a city, a postal code, a country, or a bounded area.

Station identifierCity or postal codeCountry and fuel typeBounding area

History

Historical station pulls with availability checks.

Request a time window for station-level history. The API should confirm coverage before counting the request.

Start and end datesRecent daily historyCountry availabilityNo-charge unavailable history

Aggregates

Average prices by brand, location, and time.

Use aggregate pulls for weekly or daily averages by brand, city, postal code, region, country, or fuel type.

Brand averageCity or postal-code averageWeekly market averageCountry trend window

How a request is made

Commercial requests use HTTPS, an API key, a scoped country, and explicit filters. The exact response contract is provided in the customer portal after access is approved.

1Choose row-level station data or aggregate market data.

2Provide country, fuel type, location or brand filters, and an optional time window.

3Use a preflight or validated request path to confirm coverage before a billable pull.

4Only successful data responses count toward quota or overage.

Billing and quota safety

The intended billing rule is simple: customers should pay for successful data access, not for mistakes, unavailable markets, or unsupported history windows.

Counts toward quota

Authenticated request returns current station data.
Authenticated request returns available station history.
Authenticated request returns an aggregate result for a supported market and time window.

Does not count

Missing or invalid API key.
Invalid parameters or unsupported filters.
Country, city, station, brand, or history window is unavailable.
Validated request returns no supported data for the requested scope.
Server-side failure before a usable data response is delivered.

What still needs to be enforced in the API layer

The customer account, pricing, and checkout flow are live. The next backend step is to put the commercial API behind API-key validation, usage counting, and Stripe overage reporting.

API keys tied to organization entitlementsMonthly request counters by key and subscriptionPreflight availability checks that are not billableOverage usage reporting only after included quota is exceeded

View pricing