AdresDirect 365: manual

How it works

AdresDirect 365 adds the House No. field, right after Post Code, on customers, vendors, contacts, ship-to addresses, vendor order addresses, locations and the company information. When someone types a Dutch post code and a house number there, the app looks the address up in the BAG and fills in the standard fields of Business Central.

The request goes straight from your Business Central environment to the BAG API Individuele Bevragingen of the Kadaster, with your own API key. No server of Van Oosten Software sits in between. Each request carries only the post code and, when there is one, the house number, and the app waits at most five seconds for an answer.

By default the app looks up only while someone types on a card. Addresses that come in through an import, a configuration package, an API integration or other code are looked up only when Look Up for Imports and APIs is on.

If the lookup does not succeed, everything stays as it was; when someone is typing, a notification says why. Saving is never blocked.

Before you start

This is what you need:

• Business Central online, Essentials or Premium, version 28 or later.
• An API key of your own for the BAG API Individuele Bevragingen. The Kadaster issues it free of charge to your organisation; you request it with the Kadaster's request form, which the Request an API Key action on the setup page opens. The key arrives by e-mail, usually within an hour on working days during office hours. See also The Kadaster's key and limits, below.
• In a sandbox: permission for outbound HTTP requests (see Setting up).
• For whoever maintains the setup: the AdresDirect 365 permission set or a broader one (see Permissions).

The Kadaster's key and limits

The Kadaster sets terms for the use of the BAG API Individuele Bevragingen. The main ones:

• A key belongs to the organisation it was issued to, and only that organisation may use it. Do not share it with other organisations. That is why Van Oosten Software does not provide a key: every organisation requests its own.
• At most 50,000 requests a day, a count that starts again after midnight, and at most 50 requests a second.
• The API is meant for looking up one or a few addresses, not for bulk. For large numbers of addresses the Kadaster offers BAG Extract and BAG GeoPackage.

That is why the app looks up only while someone types by default, and why Look Up for Imports and APIs is off by default. A post code without a house number that is already in the Post Codes table costs no request.

Questions about your key or about the BAG itself are answered by the Kadaster's BAG customer service, on +31 88 183 34 00. The request form and the Kadaster's guidelines are at the bottom of this page, under At the Kadaster.

Setting up

Search Business Central for AdresDirect 365 Setup, or open the page from Manual Setup. Then:

1. If you do not have a key yet, choose Request an API Key. That opens the Kadaster's request form; request the key in the name of your own organisation. It arrives by e-mail, usually within an hour on working days during office hours.
2. That e-mail also gives a base URL for the API. You do not need to enter it anywhere, because the app already knows it: only the key goes into Business Central.
3. Paste the key into the API Key field. Once saved, the field shows only ********.
4. Choose Test Connection. The app sends one request to the BAG and tells you whether the key was accepted.
5. Switch on Enabled.
6. Check Country/Region Code (NL by default), Fill County with Province, Save Post Codes and Look Up for Imports and APIs. The defaults suit most companies.

In a sandbox

A sandbox does not let apps make outbound HTTP requests by default. Open Extension Management, choose AdresDirect 365, choose Configure and turn on Allow HttpClient Requests. Without that permission the app cannot reach the BAG.

Daily use

Type the post code and the house number on an address card. As soon as you leave the field, the app fills in:

• Address: the street and the house number.
• City: the place as the BAG names it.
• County: the province of the post code, when Fill County with Province is on.
• Post Code: rewritten as 1234 AB, even if you typed 1234ab.

The order does not matter: the app looks up as soon as you change the post code or the house number, and uses what is there at that moment.

If you type only a post code, the app fills in City and County, but not the street: one post code can span two streets. If the post code is already in the Post Codes table, the city comes from there, without a request to the BAG.

House numbers with a letter or addition

Type the house number the way you are used to: 12, 12a, 12 A, 12-2 or 12B bis. The number first, then any letter or addition. Whatever follows the number, the app compares with house letter and addition together, as the BAG knows them. Spaces, hyphens, slashes, full stops and capitals make no difference.

Only while someone types, by default

By default the app looks up only while a user types on a card. When addresses come in through an import, a configuration package, an API integration or other code, the app looks them up only when Look Up for Imports and APIs is on. Even then there are no notifications and no pick list: if nothing matches exactly or the lookup fails, the address stays as it came in. Leave the setting off for large imports: the BAG API is not meant for bulk, and a large import can use up the daily limit of your key.

Pick an Address

If no address matches exactly, for example when you type 14 and only 14A and 14B exist, the Pick an Address list opens with the addresses at that number. Choose the right one and confirm with OK. If you close the list without choosing, the fields stay as they were.

The setup page

AdresDirect 365 Setup has these fields and actions. Everything applies per company.

API Key

Your key for the BAG API Individuele Bevragingen. It is stored encrypted in the isolated storage of this company and never shown again: the field shows ********. If you clear the field, the key is removed and Enabled is switched off.

Enabled

Whether addresses are looked up. Can only be switched on once a key is stored; otherwise the page says Enter the BAG API key first.

Country/Region Code

The country/region code of the Netherlands in this company, NL by default. Addresses with another country are not looked up. An address without a country is looked up when the company itself is in this country.

Fill County with Province

Whether the County field is filled with the province, on by default. The BAG has no provinces; the app derives the province from the first four digits of the post code.

Save Post Codes

Whether every post code found is added to the Post Codes table, on by default. Business Central then fills in the city of such a post code by itself.

Look Up for Imports and APIs

Whether addresses are also looked up when they are not typed by a user on a card, but come in through code, a configuration package or import, or an API integration. Off by default. The Kadaster's key is not meant for bulk: leave this off for large imports.

Test Connection

Action. Sends one request with the stored key to the BAG and tells you whether it was accepted.

Request an API Key

Action. Opens the Kadaster's request form, where you request a free key for your organisation.

If the address does not appear

If the lookup does not succeed while someone is typing, the fields stay as they were and a notification appears at the top of the page. What the notifications mean:

Nothing happens at all, no address and no notification? Then check:

• that Enabled is on in AdresDirect 365 Setup;
• that the country on the address is the one in the setup (NL by default), or empty in a company that is itself in that country;
• that the post code has four digits and two letters, like 1234 AB. A Dutch post code never starts with 0;
• for an import or integration: that Look Up for Imports and APIs is on. Notifications appear only while someone types.

The Post Codes table

With Save Post Codes on (the default), the app puts every post code it finds, with city, country and province, into the standard Post Codes table of Business Central. That table then works as a memory: when someone types a post code that is already in it, the city comes from there, without a request to the BAG.

The table holds no streets and no house numbers. A user without write permission on the Post Codes table still gets the address; only the table does not grow. The post codes belong to Business Central, not to the app: they stay when you uninstall the app.

Permissions

Users who enter addresses need no extra permission set: the lookup carries its own permissions. The AdresDirect 365 permission set (object VOA AdresDirect 365) is for whoever maintains AdresDirect 365 Setup.

Several companies

Settings and API key apply per company. Set up each company in which you want addresses looked up separately: enter the key, test the connection, switch it on. In a company without settings, nothing changes in how Business Central works.

Sources

Addresses come from the Basisregistratie Adressen en Gebouwen (BAG) of the Kadaster, through the BAG API Individuele Bevragingen. The BAG is open data (CC0). The province per post code area is derived from GeoNames data (geonames.org), under the Creative Commons Attribution 4.0 licence (CC BY 4.0): a table of 4,086 areas.

Need help?

If your question is not answered in this manual, e-mail info@van-oosten.nl. The Support page says what to send along.