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.

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

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.