# Oracle-inzichten

De oracle geeft tellingen uit aangeleverde gegevens per viercijferig postcodegebied en UTC-uur. Je gebruikt een API-key met `oracle:read`. De beschikbaarheid hangt af van de omgeving en de hoeveelheid bruikbare gegevens; vraag je contactpersoon bij vlows naar de mogelijkheden.

## Welke aanvraag kies je?

| Waarde voor `{metric}` | Volledig pad | Betekenis |
| --- | --- | --- |
| `activity` | `/deliveries/v1/oracle/activity` | Unieke pakketten met minstens één gebeurtenis in het postcodegebied en uur. |
| `planned` | `/deliveries/v1/oracle/planned` | Pakketten waarvan het geplande tijdvak in het uur begint. |
| `coverage` | `/deliveries/v1/oracle/coverage` | Metadata over dekking, actualiteit en publicatiegrenzen. |

Dit zijn tellingen van pakketregistraties van deelnemers. Ze zijn geen aantal voertuigen of stops, geen voorspelling en geen marktaandeel.

## Invoervelden

Alle aanvragen zijn GET-verzoeken met `Authorization: Bearer <key>`, zonder JSON-body. Voor `activity` en `planned` zijn de volgende drie queryparameters verplicht:

| Queryveld | Formaat | Regels | Voorbeeld |
| --- | --- | --- | --- |
| `pc4` | Tekst van vier cijfers | Eerste cijfer 1–9; geen spaties of postcodeletters. | `9901` |
| `from` | Geheel getal, Unix-seconden UTC | Begin op een heel UTC-uur, inclusief. | Een veelvoud van 3600. |
| `to` | Geheel getal, Unix-seconden UTC | Einde op een heel UTC-uur, exclusief en groter dan `from`. | `from + 3600` voor één uur. |

De periode is maximaal zeven dagen. `from` mag niet meer dan 30 dagen vóór het aanvraagmoment liggen en `to` niet meer dan 30 dagen erna. Beide grenzen moeten deelbaar zijn door 3600. Voor `coverage` zijn deze queryvelden niet nodig.

Gebruik elke parameter één keer. Extra filters, een volledige postcode zoals `9901KB`, meerdere postcodegebieden, een gemeente-ID of een vervoerdersfilter worden bij de tellingen niet geaccepteerd.

## Een periode opvragen

Dit voorbeeld berekent het vorige hele UTC-uur. Het gebruikt Python om een actueel, geldig tijdvak te maken.

```sh
FROM=$(python3 -c 'import time; print((int(time.time()) // 3600 - 1) * 3600)')
TO=$((FROM + 3600))
curl --fail-with-body --silent --show-error --get \
  'https://api.vlows.io/deliveries/v1/oracle/activity' \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode 'pc4=9901' \
  --data-urlencode "from=$FROM" \
  --data-urlencode "to=$TO"
```

Vervang de postcode door je gewenste PC4. Gebruik `/planned` voor geplande pakketten. Omdat het einde exclusief is, vraagt 08:00–09:00 precies het uur vanaf 08:00 op; de cel van 09:00 hoort niet bij het antwoord.

## Antwoordvelden bij een telling

| Veld in `data` | Type | Betekenis |
| --- | --- | --- |
| `pc4` | Tekst | Opgevraagd postcodegebied. |
| `metric` | Tekst | `activity` of `planned`. |
| `cells` | Lijst | Eén cel per opgevraagd UTC-uur, ook bij onderdrukte waarden. |
| `cells[].bucket` | Geheel getal | Begin van het uur in Unix-seconden UTC. |
| `cells[].count` | Geheel getal of `null` | Gepubliceerd aantal, naar beneden afgerond op een veelvoud van 5, of geen gepubliceerd aantal. |
| `cells[].suppressed` | Boolean | `true` als het aantal niet wordt gepubliceerd. |
| `updated_at` | Datumstring | Laatste update in RFC 3339-formaat. |
| `resolution` | Tekst | `hour`. |
| `rounding` | Geheel getal | `5`: de afrondingsstap. |

Een cel wordt pas gepubliceerd bij minstens drie organisaties en tien pakketten. **`null` is geen nul verkeer.** Het kan betekenen dat er te weinig data of te weinig spreiding is. Lees bij een onderdrukte cel daarom niet alsof er nul pakketten waren.

## Dekking opvragen

```sh
curl --fail-with-body --silent --show-error \
  'https://api.vlows.io/deliveries/v1/oracle/coverage' \
  -H "Authorization: Bearer $API_KEY"
```

Je hoeft geen postcode of periode in te vullen. De response bevat:

| Veld in `data` | Betekenis |
| --- | --- |
| `updated_at` | Laatste update; kan `null` zijn als er nog geen update is. |
| `coverage` | `participant_data_only`: alleen aangeleverde data van deelnemers. |
| `market_share` | `null`: er wordt geen marktaandeel verstrekt. |
| `resolution` | `PC4/hour`. |
| `minimum_organizations` | `3`: minimaal aantal organisaties voor een publiceerbare cel. |
| `minimum_parcels` | `10`: minimaal aantal pakketten voor een publiceerbare cel. |

## Fouten en beschikbaarheid

| Antwoord | Waarschijnlijke oorzaak | Vervolg |
| --- | --- | --- |
| `400 invalid_area` | Geen geldige PC4. | Gebruik vier cijfers, bijvoorbeeld `9901`. |
| `400 invalid_period` | Geen hele uren, ongeldige volgorde, te lange of te verre periode. | Bereken beide UTC-grenzen opnieuw. |
| `400 invalid_filter` | Onbekend of dubbel queryveld. | Gebruik alleen één `pc4`, één `from` en één `to`. |
| `403` | Key mist `oracle:read`. | Controleer de rechten in de console. |
| `404` | Niet-ondersteunde metric. | Kies `activity`, `planned` of `coverage`. |
| `503 oracle_stale` | Geen voldoende recente telling beschikbaar; grens is vijf minuten. | Probeer later opnieuw en controleer coverage. |
| `503 oracle_not_enabled` | Oracle is niet beschikbaar in de omgeving. | Vraag je contactpersoon bij vlows naar de beschikbaarheid. |

Er is nog geen complete gemeentelaag, realtime stream of marktbrede dekking. Zie [Functies & beschikbaarheid](/platformstatus/).