Doffin Public API: muligheter og begrensninger

Doffin Public API v2 ble gjort åpent tilgjengelig i 2023 og brukes nå av anbudsregisteret til å hente Doffin-delen av basen (110 466 kunngjøringer). APIet er gratis, krever en enkel registrering av API-nøkkel, og returnerer JSON-data om kunngjøringer i sanntid. For en leverandør som vil bygge egen integrasjon eller utvide funksjonaliteten i et eksisterende anbudsverktøy, er APIet det viktigste tekniske grunnlaget.

For deg som ikke planlegger å bygge egen kode, er APIet likevel verdt å forstå fordi det forklarer hvilke begrensninger som finnes i selve datakilden. De fleste anbudsverktøy på markedet bygger på samme API som vi gjør, og kvaliteten på sluttproduktet avhenger av hvor godt de håndterer rammene som APIet setter.

Hva Doffin Public API tilbyr

APIet eksponerer fire hovedfunksjoner. Først har du søkeendepunktet som returnerer en liste over kunngjøringer basert på filtre. Du kan filtrere på status (aktiv, utgått, tildelt, avlyst), CPV-koder, geografi (NUTS-koder), oppdragsgiver og publiseringsdato. Hvert søk returnerer maks 15 resultater per side, og du kan paginere deg gjennom flere sider.

Det andre endepunktet er detaljuthenting for én konkret kunngjøring basert på Doffin-ID. Det returnerer fullstendige metadata: tittel, beskrivelse, alle CPV-koder, NUTS-koder, frist, kontaktinformasjon, verdier og lenker til eventuelle vedlegg.

Det tredje endepunktet er nedlasting av eForms-XML for kunngjøringer publisert etter 25. oktober 2023. Det er den underliggende strukturerte datamodellen, og inneholder mer detaljerte felter enn det som vises i den brukerorienterte responsen fra søkeendepunktet. For maskinelle integrasjoner er eForms-XML ofte den primære kilden.

Det fjerde endepunktet handler om tildelinger (F03 i eldre kunngjøringer, eForms subtype 29 i nyere). Her kan du hente data om hvem som vant en konkret konkurranse, kontraktsverdi, og leverandørenes organisasjonsnummer.

Begrensninger i APIet

APIet har en kjent kapasitetsgrense som påvirker hvordan anbudsverktøy må designes. Hvert søk returnerer maksimalt 1000 «accessible» kunngjøringer, uansett filter. Hvis du filtrerer på en bred kategori med over 1000 treff, returnerer APIet kun de 1000 første og signaliserer at det finnes flere. For å fange opp alt må du segmentere søket ditt med smalere filtre, typisk per CPV-hovedkategori eller per publiseringsdato.

Dette er ikke en bug, det er en bevisst beskyttelse mot for store nedlastinger. For anbudsregisteret betyr det at vi kjører tidsplanlagte jobb som splitter søk per CPV-hovedkategori for å fange opp alt som ligger i basen. Hvis du bygger din egen integrasjon, må du designe rundt samme begrensning.

En annen begrensning er at frigjengelige datofilter ikke alltid fungerer som forventet. Vår erfaring er at parametere som publishedFromDate, updateFromDate og lastUpdatedFromDate blir ignorert av søkeendepunktet, og returnerer samme resultatsett uansett hva du oppgir. For å filtrere på tid må du i praksis sortere resultatene og selv plukke ut det som er nytt. Det er en irriterende begrensning som mange førstegangsbrukere av APIet bruker tid på å oppdage.

Det tredje begrensningen handler om vedlegg. APIet returnerer en documents_url-lenke som peker til hvor vedleggene ligger, men selve vedleggene er som regel hostet på leverandørportaler (Mercell, Visma TendSign, EU-Supply, Opic). Disse portalene krever ofte registrering og innlogging for å laste ned dokumenter. APIet alene gir deg derfor ikke direkte tilgang til konkurransegrunnlaget, kun til metadata om kunngjøringen og lenker du må følge separat. Vi skrev en egen artikkel om hvorfor vedlegg mangler i Doffin som forklarer dette problemet mer i detalj.

Hvordan komme i gang med APIet

For å bruke Doffin Public API trenger du en API-nøkkel. Den får du gratis ved å registrere deg på Doffins utviklerportal (developer.doffin.no eller tilsvarende per gjeldende dokumentasjon). Etter registrering får du en nøkkel som inngår i alle dine API-kall som en header.

Det enkleste praktiske utgangspunktet er å hente én konkret kunngjøring basert på Doffin-ID. Det krever et HTTP GET-kall mot endepunktet /public/v2/notices/{id} med API-nøkkelen som header. Responsen er JSON med alle metadata om kunngjøringen. Dette tester at registreringen din fungerer og at nøkkelen er gyldig.

Når det grunnleggende fungerer, kan du gå videre til søk. Et bredt søk uten filter returnerer de nyeste 15 kunngjøringene. Du legger til filtre etter behov: CPV-kode for bransje, status for å begrense til aktive anbud, geografi for å begrense til et fylke. Hver filtertype kan kombineres.

For en utvikler er det praktisk å skrive en wrapperfunksjon som håndterer pagineringen automatisk, henter alle resultater opp til 1000-grensen, og deretter segmenterer videre hvis nødvendig. Det er den samme strategien anbudsregisteret bruker, og det er nødvendig for å bygge et komplett bilde av markedet.

Hva APIet ikke gir deg

Det er noen viktige datatyper som ikke er tilgjengelige via Doffin Public API, og det er verdt å vite dem før du bygger en integrasjon.

Konkrete tilbud og prisinformasjon er ikke tilgjengelig. APIet returnerer estimerte verdier og kontraktverdier ved tildeling, men ingen detaljer om enkelttilbud, evalueringspoeng eller intern tilbudsdokumentasjon.

Klage-statistikk og KOFA-avgjørelser er ikke i Doffin-APIet. For å analysere klagemønstre må du gå til Klagenemndssekretariatets egen statistikkportal eller hente data fra deres separate kanaler.

Detaljert geografisk informasjon om hvor i en kommune en kontrakt skal utføres er ikke alltid presist. NUTS-koden går ned til fylkesnivå, ikke til konkrete adresser. For lokale leverandører kan dette være en begrensning fordi to oppdrag i samme NUTS-region kan være på vidt forskjellige steder.

Markedsdialog-informasjon, det vil si kommunikasjonen mellom oppdragsgiver og leverandører før selve utlysningen, er ikke i APIet. Det er separate prosesser som dokumenteres ulikt og som ikke er offentlig tilgjengelig.

Når du bør vurdere å bygge på APIet

For en leverandør med 5-50 ansatte er det sjelden lønnsomt å bygge egen integrasjon mot Doffin API, fordi det krever utviklingsressurser og løpende vedlikehold. Eksisterende anbudsverktøy som anbudsregisteret, Mercell, Visma og andre dekker de fleste praktiske behov og er rimeligere enn å bygge eget.

Det finnes likevel tre scenarier der egen integrasjon kan gi verdi. Det første er hvis du har spesifikke interne systemer der anbudsinformasjon skal integreres med CRM, ERP eller bid-management. Det andre er hvis du har skarpe filtreringsbehov som ikke dekkes av eksisterende verktøy, for eksempel kombinasjoner av tekstanalyse og strukturerte felter. Det tredje er hvis du planlegger å videreformidle anbudsdata til andre, og må kontrollere kilder og oppdateringsfrekvens selv.

For de fleste leverandører er den bedre veien å bruke et eksisterende verktøy og fokusere innsatsen på selve tilbudsarbeidet, ikke på datainnhenting.

Hvordan API-volumet henger sammen med markedet

For å gi en konkret følelse av størrelsesordenen: anbudsregisteret henter mellom 800 og 1500 nye eller oppdaterte kunngjøringer fra Doffin-APIet hver dag, fordelt over flere planlagte jobber. Den mest aktive jobben kjører hvert 30. minutt og henter de nyeste 990 kunngjøringene per kjøring. På toppen av det kjører en daglig jobb klokken 02:30 som chunker etter CPV-hovedkategori for å fange opp anbud som kan ha falt utenfor 1000-grensen i 30-minuttersjobben.

For en utvikler som planlegger egen integrasjon er det viktig å forstå at APIet ikke har push-mekanisme. Du må polle, og oppdateringsfrekvensen din avgjør hvor raskt nye anbud dukker opp i ditt system. Hvis du poller én gang i timen, kan en kunngjøring publisert klokken 10:01 først bli synlig i ditt system klokken 11. For aktiv tilbudsjakt der hver dag teller, er det sjelden raskt nok.

En praktisk konsekvens er at APIet egner seg bedre for analytisk bruk enn for raskt operativ bruk. Hvis du vil overvåke markedet i sanntid, er du som regel bedre tjent med et tredjepartsverktøy som har optimert polling-frekvens og varslingsmekanismer, og som distribuerer kostnaden over mange brukere.

En tredje begrensning som ofte overses er kvaliteten på fritekstfeltene. Beskrivelser i kunngjøringer er fritekst skrevet av innkjøpere, og kvaliteten varierer enormt. Noen kunngjøringer har 5-10 setninger med presis fagbeskrivelse, andre har 1-2 generiske setninger som ikke sier mye om det faktiske oppdraget. For automatisk klassifisering eller maskinlæring er dette en utfordring, fordi det ikke er enkelt å trene på data med så ujevn kvalitet. Vi har observert at fritekstfeltenes lengde varierer fra 50 tegn til over 5000, og det henger ikke alltid sammen med kontraktsverdien eller kompleksiteten i oppdraget.

Sammenlignet med andre offentlige API-er

Doffin-APIet er ikke unikt i Europa. EU-kommisjonen har sitt eget TED-API, og hvert medlemsland har som regel egne nasjonale API-er for offentlige anbud. Norske leverandører som vurderer å konkurrere i EU-anbud bør også kjenne til TED-APIet, som er åpent og dekker hele EØS-området, inkludert de norske anbudene som krysser EØS-terskel.

Sammenlignet med Danmarks tilsvarende API (administrert av Konkurrence- og Forbrugerstyrelsen) og Sveriges Visma TendSign-API, er Doffin Public API av sammenlignbar kvalitet. Det har samme grunnleggende begrensninger på sidestørrelse og kapasitet, men det er mer veldokumentert enn flere av motpartene. For en utvikler som vil bygge nordisk dekning, er TED-APIet ofte det viktigste enkelte verktøyet fordi det dekker alle EØS-anbud over terskel i ett kall.

Tekniske detaljer som ofte forvirrer

Tre tekniske aspekter ved APIet skaper konsekvent forvirring blant utviklere. Det første er kunngjøringstypene, som varierer mellom gamle TED-skjemaer (F01-F03) for kunngjøringer eldre enn oktober 2023 og nye eForms-subtyper (notice subtypes 1-40+) for senere. Du må håndtere begge formatene i samme datapipeline, og mappingen mellom dem er ikke alltid intuitiv.

Det andre er datatypene i feltene. Verdier kan komme som tall, strenger eller objekter avhengig av kunngjøringstype, og samme felt kan ha ulikt format i ulike kunngjøringer. Du må forsvare deg mot dette ved å parse defensivt og håndtere uventede strukturer.

Det tredje er språkhåndtering. Norske kunngjøringer er primært på norsk, men noen større anbud over EØS-terskel publiseres også på engelsk via TED. Hvis du henter samme kunngjøring fra Doffin og TED, kan tekstinnholdet være på ulike språk, og det krever at du tar bevisst stilling til hvilken kilde du anser som primær.

Et fjerde aspekt som ofte overses er at organisasjonsnummer i feltene for oppdragsgiver og vinnere ikke alltid er fylt ut konsistent. Statlige etater og kommuner har organisasjonsnummer, men enkelte underliggende foretak kan dukke opp med tomt felt eller med moderorganisasjonens nummer. For mapping mot Brønnøysund og kobling til regnskapsdata må du være forberedt på å håndtere disse tomme tilfellene defensivt, ellers risikerer du å miste data i prosessering.

Praktisk eksempel: hva et søk kan returnere

For å konkretisere hva APIet faktisk gir tilbake, kan vi se på et typisk søk. Et kall mot søkeendepunktet med filter status=ACTIVE og cpv=72260000 (programvareutvikling) returnerer typisk 50 til 150 treff på et gjennomsnittlig dag. For hvert treff får du tilbake en JSON-objekt med følgende nøkkelfelter: kunngjørings-ID, tittel, beskrivelse, oppdragsgiver med organisasjonsnummer, publiseringsdato, frist, estimert verdi, alle CPV-koder, alle NUTS-koder, dokumentlenker, og en lenke til detaljendepunktet hvis du vil ha alle felter.

For en utvikler er det ofte praktisk å gå direkte på detaljendepunktet etter at du har identifisert relevante kunngjøringer i søkeendepunktet, fordi detaljresponsen inneholder de fulle eForms-feltene som du trenger for skikkelig analyse. Søkeresponsen er optimalisert for hurtig listing, ikke for komplett datauthenting.

Underliggende er Doffin Public API et solid, men ikke perfekt, verktøy som lar deg bygge en strukturert tilnærming til offentlige anbud. For de fleste leverandører er det ikke nødvendig å gå direkte mot det selv, fordi eksisterende verktøy gjør jobben med integrasjon på en bedre måte. Men det er nyttig å forstå hva som ligger under fordi det forklarer både mulighetene og begrensningene i alle anbudsverktøy på markedet.

For å forstå hvordan Doffin generelt fungerer som datakilde, se Doffin-guide, feltene i en Doffin-kunngjøring og Doffin-statusene forklart. For å forstå forskjellen mellom Doffin og europeisk TED-system, se Doffin vs TED.