# Glossary

This page defines the terms used across the Pumperly documentation. Each entry is short and links to the page that covers the term in depth.

## Alternate route

A second or third way to drive between the same two points. For a plain trip from A to B, Pumperly asks [Valhalla](<#valhalla>) for up to 2 alternates and shows them next to the main route. A trip with [waypoints](<#waypoint>) gets one route only. See [`POST /api/route`](<https://geiserx.github.io/Pumperly/reference/api/#route>).

## Bounding box (bbox)

A rectangle on the map, given as four numbers: `minLon,minLat,maxLon,maxLat`. The map sends the visible area as a bounding box to [`/api/stations`](<https://geiserx.github.io/Pumperly/reference/api/#stations>).

## BNetzA

The Bundesnetzagentur, Germany's federal network agency. It publishes the Ladesäulenregister, the official register of public charge points in Germany. Every operator of a public charge point must file its chargers there. Pumperly can download the register as one file, with no API key, when `PUMPERLY_DE_EV_SOURCE=bnetza`. By default it uses [OCPDB](<#ocpdb>), which contains the register. Its [scraper key](<#scraper-key>) is `EV_DE_BNETZA`. See [EV charging sources](<https://geiserx.github.io/Pumperly/data/ev-sources/index.md>).

## Corridor

The strip of land either side of a planned route in which Pumperly looks for stations. Its half-width is set in kilometres, from 0.5 to 50, and defaults to 5. A station is in the corridor when its shortest distance to the route line, measured on the globe, is within that width. The corridor slider in the route panel changes it. See [Planning a route](<https://geiserx.github.io/Pumperly/using/routes/index.md>) and [`POST /api/route-stations`](<https://geiserx.github.io/Pumperly/reference/api/#route-stations>).

## Currency

Each stored price carries the ISO 4217 code of the currency its [source](<#source>) publishes it in, such as `EUR` or `HUF`. Pumperly stores prices unconverted. The browser converts them for display. See [Currencies and exchange rates](<https://geiserx.github.io/Pumperly/reference/currencies/index.md>).

## Detour

The extra driving time, in minutes, that stopping at a station adds to a trip. Pumperly computes it with [Valhalla](<#valhalla>) in one of two ways:

- **Route-relative:** the time to drive from a point on the route before the station, through the station, to a point after it, minus the time the route itself takes between those two points. This measures the detour from the route you are on.
- **Whole trip:** the time from origin through the station to destination, minus the original route's time. This measures the best detour over any route.

See [`POST /api/route-detour`](<https://geiserx.github.io/Pumperly/reference/api/#route-detour>).

## ECB reference rates

The daily euro exchange rates published by the European Central Bank. Pumperly uses them to convert prices between currencies, with fixed [fallback rates](<https://geiserx.github.io/Pumperly/reference/currencies/#fallback-rates>) for a few currencies the ECB does not publish. See [The ECB feed](<https://geiserx.github.io/Pumperly/reference/currencies/#the-ecb-feed>).

## Empty-fetch guard

A safety check in every [scraper](<#scraper>) run. If a fetch returns no stations to store, the run stops before it deletes or replaces anything. A source that answers with an empty or broken file therefore cannot wipe a country off the map. See [How scrapers work](<https://geiserx.github.io/Pumperly/data/how-scrapers-work/index.md>).

## Enabled countries

The countries an instance scrapes. They come from [`PUMPERLY_ENABLED_COUNTRIES`](<https://geiserx.github.io/Pumperly/reference/environment-variables/#pumperly_enabled_countries>), a comma-separated list of country codes or [scraper keys](<#scraper-key>). When it is unset, every country with a scraper is enabled. Enabling a country also enables its [EV\_XX key](<#ev-xx-key>). Disabling a country stops its scrapers. It does not delete the rows already stored. See [Countries and scrape schedule](<https://geiserx.github.io/Pumperly/configuration/countries-and-schedule/index.md>).

## EV\_XX key

The [scraper key](<#scraper-key>) for a country's EV chargers from [OpenChargeMap](<#ocm>), where `XX` is the country code: `EV_FR`, `EV_IT` and so on. Listing `FR` in the [enabled countries](<#enabled-countries>) turns on `EV_FR` too, unless [`PUMPERLY_EV_ENABLED`](<https://geiserx.github.io/Pumperly/reference/environment-variables/#pumperly_ev_enabled>) is `0`. `EV_US` exists without a matching fuel scraper, so listing `US` gives EV chargers only. Spain and Germany have more EV keys: `EV_ES_REVE` for Spain, `EV_DE_OCPDB` and `EV_DE_BNETZA` for Germany. Only one key per country ever runs. See [handover](<#handover>).

## External ID

A station's identifier at its [source](<#source>). Together with the country code it is the key a scraper writes on: a re-import updates the same row instead of adding a new one, and share links use this pair. For [BNetzA](<#bnetza>) and [OCPDB](<#ocpdb>) chargers the ID is built from the coordinates, so it changes when an operator corrects a position. Some sources get a prefix, such as `ocm-` for [OpenChargeMap](<#ocm>) and `reve-` for [REVE](<#reve>). The database's own UUID can change, so do not store it. See [Data model](<https://geiserx.github.io/Pumperly/reference/data-model/index.md>).

## Fuel code

The short code Pumperly uses for a fuel, such as `B7` for diesel or `E10` for petrol with up to 10% ethanol. The core codes, such as `E5`, `E10` and `B7`, follow the European standard EN 16942. `EV` is a code too, for charge points. See [Fuel types](<https://geiserx.github.io/Pumperly/reference/fuel-types/index.md>).

## Fuelo.net

A community-sourced fuel price site that covers many countries in Europe and nearby. One shared Pumperly scraper reads it for twelve countries, among them Switzerland, Poland and the Czech Republic. Fuelo.net currently refuses those requests, so these countries are paused. See [Fuel price sources](<https://geiserx.github.io/Pumperly/data/fuel-sources/#fuelo>) and [Coverage and status](<https://geiserx.github.io/Pumperly/data/coverage/index.md>).

## GeoJSON

A standard JSON format for map data. Pumperly returns stations as a GeoJSON `FeatureCollection` of `Point` features, and routes as `LineString` geometries. Coordinates are always `[longitude, latitude]`.

## Handover

The switch from one [source](<#source>) to another for the same data, done without leaving the map empty in between. For Spain, [REVE](<#reve>) takes over EV chargers from [OpenChargeMap](<#ocm>) once a REVE key is set. REVE fills in slowly, over about a day and a half, so the OpenChargeMap rows stay until REVE holds 95% of its registry by default, and are deleted then. For Germany, [OCPDB](<#ocpdb>) or [BNetzA](<#bnetza>) takes over after its first healthy run, because each arrives complete in one run. That run must refresh a minimum number of stations before it may delete anything, so a broken download cannot remove working rows. Sweden's fuel scraper uses the same kind of floor when it retires the rows of an older source. See [EV charging sources](<https://geiserx.github.io/Pumperly/data/ev-sources/index.md>).

## Latest price

The price Pumperly shows for a station and fuel: the stored price with the newest `reported_at` time. `reported_at` is when Pumperly's scraper stored the price, not when the source published it.

## NDJSON

Newline-delimited JSON: one complete JSON object per line. [`POST /api/route-detour`](<https://geiserx.github.io/Pumperly/reference/api/#route-detour>) streams its results in this format, so each station's detour appears as soon as it is known.

## OCM (OpenChargeMap)

[OpenChargeMap](<https://openchargemap.org>), a crowdsourced, worldwide registry of EV charge points, published under the Open Database License. It is Pumperly's default EV source for every country except Germany. It needs a free API key in [`PUMPERLY_OCM_API_KEY`](<https://geiserx.github.io/Pumperly/reference/environment-variables/#pumperly_ocm_api_key>). Without one, the OpenChargeMap scrapers fetch nothing. See [EV charging sources](<https://geiserx.github.io/Pumperly/data/ev-sources/index.md>) and [API keys](<https://geiserx.github.io/Pumperly/configuration/api-keys/index.md>).

## OCPDB (Open ChargePoint Database)

A German charge point database run by MobiData BW. It merges the [BNetzA](<#bnetza>) register with the operators' own feeds, which carry ad-hoc prices. It is Germany's default EV source and the only one with prices: the cheapest ad-hoc tariff per kWh, plus any session and per-minute fees. It needs no API key. Its [scraper key](<#scraper-key>) is `EV_DE_OCPDB`. See [EV charging sources](<https://geiserx.github.io/Pumperly/data/ev-sources/#ocpdb>).

## Orphan cleanup

The last step of a scraper run. It deletes the country's fuel stations that no longer have a price from any source. EV chargers are never removed this way, priced or not. If any batch of station writes failed in the run, the cleanup is skipped. That stops it from deleting stations whose update never landed.

## Photon

An open-source geocoder built on OpenStreetMap data. A geocoder turns a place name into coordinates. Pumperly calls Photon for the search box on the map, through [`/api/geocode`](<https://geiserx.github.io/Pumperly/reference/api/#geocode>). Without [`PHOTON_URL`](<https://geiserx.github.io/Pumperly/reference/environment-variables/#photon_url>) the search returns no results. See [Geocoding with Photon](<https://geiserx.github.io/Pumperly/configuration/geocoding-photon/index.md>).

## PostGIS

The spatial extension for PostgreSQL. It stores each station's position as a point and answers location questions such as "which stations are inside this box" or "which are within 5 km of this line". Pumperly needs a PostgreSQL database with PostGIS enabled. See [Data model](<https://geiserx.github.io/Pumperly/reference/data-model/index.md>).

## Price band

The range of prices Pumperly accepts for a currency, such as 200 to 2,000 for Hungarian forints. EV prices have their own range: 0.10 to 2.00 EUR per kWh. A scraper drops any price outside its band before storing it. That catches placeholders and prices in the wrong unit. See [Price bands](<https://geiserx.github.io/Pumperly/reference/currencies/#price-bands>).

## Rate limit

A cap on how many requests one client IP may send to an endpoint per minute. It applies to the three route endpoints only. Going over it returns `429 Too many requests`. See [Rate limits](<https://geiserx.github.io/Pumperly/reference/api/#rate-limits>).

## REVE (Mapa REVE)

Spain's official registry of EV charge points, run by Red Eléctrica de España. Every Spanish charge point operator must file into it. Pumperly uses it for Spain's chargers when [`PUMPERLY_REVE_API_KEY`](<https://geiserx.github.io/Pumperly/reference/environment-variables/#pumperly_reve_api_key>) is set. Its API allows only 5 requests an hour, so the first full load takes more than a day. Its [scraper key](<#scraper-key>) is `EV_ES_REVE`. See [EV charging sources](<https://geiserx.github.io/Pumperly/data/ev-sources/index.md>).

## Route fraction

A station's position along a route, from `0` at the start to `1` at the end. [`POST /api/route-stations`](<https://geiserx.github.io/Pumperly/reference/api/#route-stations>) returns stations sorted by it.

## Scrape interval

How often, in hours, a [scraper](<#scraper>) runs. Each scraper has a default, from 1 hour to 24. Every scraper also runs once shortly after the app starts. `PUMPERLY_SCRAPE_INTERVAL_HOURS` sets one interval for all, and `PUMPERLY_SCRAPE_INTERVAL_<KEY>` sets one [scraper key](<#scraper-key>)'s. See [Countries and scrape schedule](<https://geiserx.github.io/Pumperly/configuration/countries-and-schedule/index.md>).

## Scraper

The code that downloads one [source's](<#source>) data, turns it into Pumperly's stations and prices, and stores it. Each one handles one country, or one country's EV chargers. Scrapers run inside the app on a timer. See [How scrapers work](<https://geiserx.github.io/Pumperly/data/how-scrapers-work/index.md>).

## Scraper key

The name a scraper is scheduled and configured under. Fuel scrapers use the country code, such as `ES`. EV scrapers use an [EV\_XX key](<#ev-xx-key>). A few have their own names: `AU_NSW` for New South Wales, `EV_ES_REVE`, `EV_DE_BNETZA`, `EV_DE_OCPDB`, and `STATIC_<SOURCE>` for each [static dataset](<#static-dataset>). The per-scraper interval variable uses the same key, as in `PUMPERLY_SCRAPE_INTERVAL_EV_ES_REVE`.

## Source

The place a scraper gets its data from: a government feed, a commercial API or a community site. Each price row stores its source name, such as `miteco` for Spain's ministry or `anwb` for the Netherlands, Belgium and Luxembourg. EV sources store no prices. A scraper run replaces only the prices of its own source in its own country, so sources never overwrite each other. See [Data sources](<https://geiserx.github.io/Pumperly/data/coverage/index.md>).

## Static dataset

Station data committed to the repository instead of fetched from the network. Each one is scheduled like a scraper under a `STATIC_<SOURCE>` key. See [Adding a country](<https://geiserx.github.io/Pumperly/data/adding-a-country/index.md>).

## Station

One place on the map: a fuel station, an EV charge point, or both. A station has a name, brand, address and position, and zero or more prices.

## Station leg

The route redrawn through a station you pick while a route is on screen. The web app sends the station to [`POST /api/route`](<https://geiserx.github.io/Pumperly/reference/api/#route>) as a [waypoint](<#waypoint>) and shows the new line. It keeps the stations it already found along the original route, so the list does not reload.

## Station type

One of `fuel`, `ev_charger` or `both`. Selecting the `EV` fuel shows stations of type `ev_charger` and `both`. See [Data model](<https://geiserx.github.io/Pumperly/reference/data-model/index.md>).

## Tankerkoenig

The service that republishes German fuel prices from the Markttransparenzstelle für Kraftstoffe (MTS-K), the federal market transparency unit for fuel. Pumperly's German fuel scraper needs a free Tankerkoenig API key in [`TANKERKOENIG_API_KEY`](<https://geiserx.github.io/Pumperly/reference/environment-variables/#tankerkoenig_api_key>). See [API keys](<https://geiserx.github.io/Pumperly/configuration/api-keys/index.md>).

## Valhalla

An open-source routing engine built on OpenStreetMap data. Pumperly uses it to plan routes and to compute [detours](<#detour>). Without [`VALHALLA_URL`](<https://geiserx.github.io/Pumperly/reference/environment-variables/#valhalla_url>), route planning is unavailable and the rest of the map still works. See [Routing with Valhalla](<https://geiserx.github.io/Pumperly/configuration/routing-valhalla/index.md>).

## Waypoint

A stop between the start and the end of a route. A route can have up to 5. Routes with waypoints get no [alternates](<#alternate-route>).
