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 address service: by default the PDOK Locatieserver, the Kadaster's open service, without a key. If you choose the BAG API Individuele Bevragingen, the request goes to 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.
• No key: by default the app uses the PDOK Locatieserver. Only if you want to use the BAG API Individuele Bevragingen do you request a free API key of your own from the Kadaster. See Two address services, 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).

Two address services

Both services deliver the addresses of the Kadaster's BAG. You choose one per company in the Address Service field on AdresDirect 365 Setup.

Choose the BAG API when new addresses must appear on the day they are registered, or when your organisation wants its own key and its own terms with the Kadaster. The app never switches to the other service by itself: an outage or a refused key stays visible in the notification.

The Kadaster's key and limits

Only for whoever chooses the BAG API. 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. The same goes for PDOK, which calls the Locatieserver a search service and points to downloads for large numbers. 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

After installing, the lookup is on, with the PDOK Locatieserver: there is nothing to set up. To check or change something, search Business Central for AdresDirect 365 Setup, or open the page from Manual Setup.

1. Choose Test Connection. The app sends one request to the chosen address service and tells you whether it answered.
2. 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.

Using the BAG API

1. In Address Service, choose BAG API Individuele Bevragingen. If no key is stored yet, Enabled is switched off.
2. 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.
3. 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.
4. Paste the key into the API Key field. Once saved, the field shows only ********.
5. Choose Test Connection. The app tells you whether the BAG accepts the key.
6. Switch on Enabled.

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 PDOK or 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 new request.

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: neither address service is meant for bulk, and with the BAG API 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.

Address Service

Where addresses are looked up: PDOK Locatieserver (the default, no key) or BAG API Individuele Bevragingen (with your own API key). If you choose the BAG API while no key is stored, Enabled is switched off.

API Key

Only with the BAG API. 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, on by default. With the BAG API it 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. Neither address service is meant for bulk: leave this off for large imports.

Test Connection

Action. Sends one request to the chosen address service and tells you whether it answered; with the BAG API also whether the key was accepted.

Request an API Key

Action, only with the BAG API. 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 new request.

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

The settings, and with the BAG API the key, apply per company. After a new installation the lookup is on in every company with the PDOK Locatieserver, also in a company you create later. If you want the BAG API, set up each company separately: choose the address service, enter the key, test the connection, switch it on.

Sources

Addresses come from the Basisregistratie Adressen en Gebouwen (BAG) of the Kadaster, by default through the PDOK Locatieserver and, if you choose, 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.