Data Api

Our Data Api can work as a stand-alone api but works seamlessly with our Maps Api service as a visual interface. Using our webhook you can build dynamic application using user generated geometries to enrich the viewer & your data. You can use /api/webhook as webhook url, to test your webhook. In the overview you can see what data is send. In the overview you can see the response of a webhook call.

The Data Api is made up of 3 distinct types of call.

  1. Geocoding
    Geocoding is the process of converting addresses (like “Utrechsestraat 61 6811 LW Arnhem”) into geographic coordinates (like X,Y coordinates in Amersfoort / RD / Rijksdriehoekscoördinaten ), which you can use to place markers on a map or find information in our Api.
  2. Data Collection
    The majority of the data is available in “Data Collection” calls. Using one identifier to retrieve the associated data
  3. Specialized calls
    Endpoints specifically build te deliver valuable data.

Basic Information Calls

This data is used to unlock the full potential of the Data Api. Using readily available information like an address.

There are 2 basic calls:

/maps_api/v2/server/data/getgeometrybyaddress

/maps_api/v2/server/data/getgeometrybyperceel

Get geometry of an address

POST /maps_api/v2/server/data/getgeometrybyaddress

Get geometry of an address

postcode and huisnummer are required

Example request:

POST /maps_api/v2/server/data/getgeometrybyaddress HTTP/1.1
Host: planviewer.nl
Accept: application/json
Content-Type: application/json

{
    "postcode" : "6811LW",
    "huisnummer" : 61,
    "huisnummertoevoeging" : "1",
    "huisletter" : "a"
}

Example response:

{
    "geometry" : "SRID=28992;POINT(190011.062 444053.666)"
}

Get geometry of a perceel

POST /maps_api/v2/server/data/getgeometrybyperceel

Get geometry of a perceel

Example request:

POST /maps_api/v2/server/data/getgeometrybyperceel HTTP/1.1
Host: planviewer.nl
Accept: application/json
Content-Type: application/json

{
    "kadastrale_gemeente" : "ARNHEM",
    "sectie" : "P",
    "perceelnummer" : "530"

}

Example response:

{
    "geometry" : "SRID=28992;POLYGON((190007.342 444029.188,190026.359 444019.629,190031.504 444034.069,190035.439 444046.094,190030.937 444047.715,190017.2 444052.877,190017.091 444052.926,190007.635 444029.962,190007.342 444029.188))"
}

Data Collection calls

Planviewer has unlocked it’s data vaults with the Data Api. A huge amount of data is now accessible but more data will become available in the future. In order to use the Data Collection calls you should first take a look at the available calls. An overview of all available calls can be found on our Data collection List page.

The data api relies on gathering the information by identifier. The identifier is a string, an integer, a ewkt geometry of a – seperated string of string values.

Within the list the identifier method is listed.
  • string
  • integer
  • geom
  • combined

Within the description it is stated what the identifier should contain. The combined identifier is used when multiple fields need to be combined to return a useful result. For example an address consist of multiple parts such as zipcode, house number and an optional house letter. When asked to provide an combined identifier there should be a description stating how the identifier should be formated. For this example it would look something like this: 6811LW,61,

Note

note that this string ends in ,. For this address there is no house letter.

As the data-api tries to answer complex questions and relies heavily on identifying data being fetched in order to do additional data api fetches. We understand that finding your way through all the possibilities in a efficient way can be challenging. Planviewer is there to offer support when you need it.

Error messages

Several errors can be gotten when using the fetch api calls. in order to help you solve the issues the errors are described with the most common solutions for the issues.

  • Constructed query encountered an issue
    There is an issue with resolving the data based on given identifier. This error either means that the identifier used does not matched the requirements or there is some configuration issue with the endpoint. If the issue persist then please contact Planviewer for support
  • Identifier parameters do not equal required paramaters
    Most likely caused by a combined identifier. Either the given combined identifier consist of too few or too many variables seperated by a comma (,). if one of the variables has a comma (,) try encoding is to solve the issue.
  • No valid query could be formed
    Generally this error will occur when an empty identifier is given

List

GET /maps_api/v2/server/data/list

Get a list of available Data Collection calls and the identifier needed to access the data

Example request:

GET /maps_api/v2/server/data/list HTTP/1.1
Host: planviewer.nl
Accept: application/json

Example response:

[
    {
        "endpoint": "gemeentebyid",
        "identifier method": "id",
        "description": "gemeentecode op basis van ID"
    },
    {
        "endpoint": "pandidbygeometry",
        "identifier method": "geom",
        "description": "verkrijg het 'pandId' op basis van geometry.\r\nKan meerdere resultaten geven"
    }
    {
    ...
    }
]

Data Collection

Every “Data Collection” call is structured the same, making is very easy to implement and use in combination with the list. All you need to use a Data Collection call is:

  1. The endpoint
  2. The identifier

Note

It is possible to gain a specific identifier for a Data Collection call from another call. Using the calls to daisy-chain the data to create increasing complex queries.

Example Data Collection call

POST /maps_api/v2/server/data/fetch/getperceelgeometrybygeometry

Get our identifier to get access to all the building information.

Example request:

GET /maps_api/v2/server/data/fetch/getperceelgeometrybygeometry HTTP/1.1
Host: planviewer.nl
Accept: application/json
Content-Type: application/json

{
    "identifier":"POINT (192890 438931)"
}

Example response:

Specialized calls

Some data is not available through the Data Collection calls and have specialized endpoints. This data is mostly generated from highly computed processes.

POST /maps_api/v2/server/data/pointcloud/building/elevation

Get the elevation of a building based on an address.

Example request:

POST /maps_api/v2/server/data/pointcloud/building/elevation HTTP/1.1
Host: planviewer.nl
Accept: application/json
Content-Type: application/json

{
    "postcode" : "6811LW",
    "huisnummer" : 61,
    "huisnummertoevoeging" : "1"
    "huisletter" : "a"
}

Example response:

POST /maps_api/v2/server/data/pointcloud/building/volume

Get the volume of a building based on an address.

Example request:

POST /maps_api/v2/server/data/pointcloud/building/volume HTTP/1.1
Host: planviewer.nl
Accept: application/json
Content-Type: application/json

{
    "postcode" : "6811LW",
    "huisnummer" : 61,
    "huisnummertoevoeging" : "1"
    "huisletter" : "a"
}

Example response:

POST /maps_api/v2/server/data/pointcloud/building/surface

Get the surface of a building based on an address.

Example request:

POST /maps_api/v2/server/data/pointcloud/building/surface HTTP/1.1
Host: planviewer.nl
Accept: application/json
Content-Type: application/json

{
    "postcode" : "6811LW",
    "huisnummer" : 61,
    "huisnummertoevoeging" : "1"
    "huisletter" : "a"
}

Example response:

POST /maps_api/v2/server/data/pointcloud/building/highestpoint

Get the highest point of a building based on an address.

Example request:

POST /maps_api/v2/server/data/pointcloud/building/highestpoint HTTP/1.1
Host: planviewer.nl
Accept: application/json
Content-Type: application/json

{
    "postcode" : "6811LW",
    "huisnummer" : 61,
    "huisnummertoevoeging" : "1"
    "huisletter" : "a"
}

Example response: