Gebruik de API, maar niet voor spam

8 maart 2012, 02:05

openkvk.nl is een database ontstaan uit een verzameling van gegevens uit verschillende bronnen waaronder kvk.nl, belastingdienst.nl en rechtspraak.nl. Deze bronnen zijn openbaar en gebonden aan wettelijke publicatie en voorwaarden. Om de data uit deze bronnen te kunnen integreren in dit systeem en doorzoekbaar te maken draaien we dagelijks onderhoudsqueries, en per kwartaal verversen we de bronnen compleet.

Beperkingen en Voorwaarden

Deze data wordt je bij normaal gebruik kosteloos aangeboden. Gebruik mag niet leiden tot overbelasting van het systeem. De dienst is dan ook toegangelijk voor eenieder die de voorgaande regel in acht neemt. Onder normaal gebruik verstaan we in ieder geval niet: het dumpen van de volledige database, op welke manier dan ook. We wijzen uitdrukkelijk nogmaals op de Databankenwet Artikel 4. Van deze dienst worden alle queries opgeslagen voor onderzoeksdoeleinden. Hiermee wordt tevens een overzicht per gebruiker van de dienst gegenereerd. Bij buitensporig gebruik krijgt de gebruiker een verwijzing. Ook limiteren we, zover wij kunnen limiteren, het hergebruik voor commerciele uitingen als Direct Marketing. Geen ingeschreven bedrijf zit te wachten op spam. Dumps van de volledige dataset worden en zijn onder strikte voorwaarden afgegeven aan derden, voor innovatieve ideeën, projecten en analyse. Zij blijven aan voorgaande beperkingen verbonden. Het gebruik van de API geschied alleen via api.openkvk.nl.

Wat faciliteren we?

Op onze API kun je Cross-Origin Resource Sharing headers vinden. Dit stelt je in staat om via AJAX requests te doen zonder dat je browser gaat zeuren over cross domain scripting. Voor Flash applicaties is er een crossdomain.xml beschikbaar. Je zou natuurlijk ook gebruik kunnen maken van je eigen reverse proxy, maar het is dus in principe niet nodig.

Simpele vragen

Het zal voor iedereen duidelijk zijn dat je veel kunt doen met een database. Maar soms ben je alleen geïnteresseerd in een enkel nummer. Er zijn momenteel een aantal interfaces beschikbaar waar je direct tegen aan kunt praten en je JSON terug krijgt. We zullen ze een voor een behandelen.

officieel.openkvk.nl

Zou het niet handig zijn om direct op de database van de Kamer van Koophandel zelf te kunnen zoeken? Ja, dat is super handig, en daarom faciliteren we het ook. Je kunt deze dienst gebruiken als je de zekerheid wilt hebben dat de data actueel is. Iedere request zorgt er tevens voor dat de data in onze eigen database wordt bijgewerkt. Hoe werkt het? http://officieel.openkvk.nl/zoekterm geeft je antwoord in JSON terug.

sphinx.openkvk.nl

Je bent alleen geïnteresseerd in een lookup naar een KvK-nummer. Daarom zoek je via onze eigen Full Text Search. Dat doe je eenvoudig via http://sphinx.openkvk.nl/programmeertaalvanjouwkeuze/zoekterm je krijgt het antwoord in het array formaat van de programmeertaal van jouw keuze terug, we ondersteunen json, php, py en ruby.

openkvk.nl/suggest/

Er ontbreekt wat in onze database, of er is wat in onze database dat een update nodig heeft. Via deze interface kun je een postcode of een KvK-nummer suggereren om bij de volgende update mee te nemen. http://openkvk.nl/suggest/kvknummer_of_postcode

Inhoud van de database

CREATE TABLE "sys"."kvk" (
        "kvk"          BIGINT,
        "bedrijfsnaam" VARCHAR(512),
        "kvks"         INTEGER,
        "sub"          INTEGER,
        "adres"        VARCHAR(64),
        "postcode"     VARCHAR(8),
        "plaats"       VARCHAR(32),
        "type"         VARCHAR(14),
        "status"       VARCHAR(256),
        "website"      VARCHAR(128),
        "vestiging"    BIGINT,
        "rechtsvorm"   VARCHAR(48),
        "lat_rad"      DECIMAL(9,9),
        "lon_rad"      DECIMAL(9,9),
        "anbi"         DATE
);

CREATE TABLE "sys"."kvk_handelsnamen" (
        "kvks"        INTEGER       NOT NULL,
        "handelsnaam" VARCHAR(256)  NOT NULL,
        "bestaand"    BOOLEAN       NOT NULL
);

CREATE TABLE "sys"."kvk_sbi" (
        "kvk"  BIGINT        NOT NULL,
        "code" VARCHAR(8)    NOT NULL
);

CREATE TABLE "sys"."sbi_codes" (
        "code"         VARCHAR(12),
        "omschrijving" VARCHAR(1024)
);

CREATE TABLE "sys"."anbi" (
        "naam"             VARCHAR(255),
        "vestigingsplaats" VARCHAR(64),
        "beschikking"      DATE,
        "einddatum"        DATE,
        "intrekking"       DATE
);

CREATE TABLE "sys"."faillissementen" (
        "kvks"         INTEGER,
        "bedrijfsnaam" VARCHAR(255),
        "plaats"       VARCHAR(32),
        "rechtbank"    VARCHAR(64),
        "rolnummer"    VARCHAR(16),
        "status"       VARCHAR(16),
        "datum"        DATE
);

Directe communicatie met de database

Om via het web queries te laten uitvoeren gebruiken wij een aangepaste DBSlayer handler van de Cherokee webserver. Een request is een correcte SQL-92 query netjes HTTP gecodeerd, en wordt verstuurd als een normale GET request. Bijvoorbeeld: /api/SELECT * FROM kvk WHERE kvks=20147376,
mocht je dit voorbeeld erg letterlijk willen nemen zet er dan minimaal LIMIT 100 achter, anders doen wij dat voor jou door middel van een redirect.

Verschillende programmeertalen gebruiken verschillende array formaten, we ondersteunen er een heleboel.

Wil je nu liever een alleen kvknummer terugkrijgen op basis van een volledige string, dan kan dat uiteraard ook.

Met de querystring ?max= kun je het aantal resultaten op de sphinx query vergroten. Voorlopig tot 1000 (limitatie in Sphinx). Ga je een webapp maken in PHP? Dan kun het beste even in het DBSlayer Cookbook kijken.

Full text search

Sphinx zit al enige tijd ook in MonetDB zelf, maar de optimiser moet nog worden getuned. De query die je in het javascript stukje is momenteel de enige vorm met een multi join die goed gaat. Er wordt aan gewerkt, als je het anders doet gaat het in plaats van in 100ms, 15s duren. Een voorbeeld;

SELECT x.kvk, x.bedrijfsnaam, x.adres, x.postcode, x.plaats, x.type,
 NOT(anbikvk.kvks is null AND anbikvk.intrekking is null) AS "anbi", status, x.kvks, x.sub
FROM
 (SELECT kvk.kvk, kvk.bedrijfsnaam, kvk.adres, kvk.postcode, kvk.plaats, kvk.type,
         kvk.kvks, kvk.sub
  FROM sphinx_searchIndex('Nieuwe Erven 2', 'openkvk') AS fts, kvk
  WHERE kvk.kvk = fts.id) AS x
LEFT JOIN anbikvk ON x.kvks = anbikvk.kvks
LEFT JOIN faillissementen ON x.kvks = faillissementen.kvk LIMIT 200 OFFSET 0;

In het bovenstaande voorbeeld zie je dat sphinx_searchIndex wordt gebruikt om een nieuwe tabel te maken, die tabel wordt gealiased als fts, free-text-search. Behalve het id komt er meer uit deze tabel terug, zoals de kans dat het bepaalde documentid overeenkomt met de zoekopdracht. Het documentid, zoals Sphinx dit noemt, is het volledige, 64bit kvk nummer. Dit omdat een Dixons in Oss hetzelfde korte (kvks) nummer heeft als de Dixons in Zaandam. De vorm van de query heeft een reden, een van die redenen is het negatief prioriseren van externe SQL-functies binnen MonetDB. Momenteel kan MonetDB geen kostenanalyse maken van een externe SQL-functie en zal de join (die enorm duur is) dus altijd verkiezen als 'minder dure'. Wil je zelf zoeken, en geen ANBI of Faillissement informatie? Dan zul je er geen last van hebben, immers, je doet geen join over alle data. Zoals je kunt zien kun je dat gebruik maken van de query tussen de (...).

Update: we hebben nu ook de optie sphinx_searchIndexLimit daarmee kun je meer dan de standaard 20 resultaten ophalen. het gebruik is ook vrij simpel:

SELECT * FROM sphinx_searchIndexLimit('vve', 'openkvk', 1000) LIMIT 1000;

Zoeken in SBI codes

We hebben momenteel een kleine 600.000 SBI codes tot onze beschikking. Deze staan in de kvk_sbi tabel. Je kunt hem op de volgende manier bevragen;

select * from kvk_sbi as a, sbi_codes as b where kvk = 27085341 and a.code = b.code;
+----------+-------+-------+---------------------------------------------------------+
| kvk      | code  | code  | omschrijving                                            |
+==========+=======+=======+=========================================================+
| 27085341 | 09.10 | 09.10 | Dienstverlening voor de winning van aardolie en aardgas |
| 27085341 | 06    | 06    | Winning van aardolie en aardgas                         |
| 27085341 | 06.10 | 06.10 | Winning van aardolie                                    |
+----------+-------+-------+---------------------------------------------------------+
3 tuples (5.488ms)