...
About
KODE stands for Kommunalt Ordresystem for Distribusjon av Eiendomsdata.
Subscribe to our email list to receive updates about our API here.
Authentication
Before you start you need to obtain the following information
| Code Block |
|---|
CLIENT_ID="my client id"
CLIENT_SECRET="my client secret"
API_USERNAME="my Infoland API username"
API_PASSWORD="my Infoland API password"
|
To get this information, please contact support@ambita.com
In order to obtain a token, run the following
| Code Block |
|---|
curl -s -H "Content-Type: application/json" https://beta-api.ambita.com:443/authentication/v2/token -d "
{
\"grant_type\": \"password\",
\"client_id\": \"CLIENT_ID\",
\"client_secret\": \"CLIENT_SECRET\",
\"username\": \"API_USERNAME\",
\"password\": \"API_PASSWORD\"
}"
|
Example response
| Code Block |
|---|
{
"access_token": "ej577asf-a5k6-42yq-a3a2-fh03hb8cb58c",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "aj274ajd-t1s8-48sk-v5m1-shf64j9bq25a",
"scope": [
"shopping.read",
"shopping.write",
"productcatalog.read"
]
}
|
The access_token is valid for 1 hour and should be reused until it expires. When the token expires, the API will return 401 UNAUTHORIZED.
To get a new access_token you can use the refresh token grant_type
| Code Block |
|---|
curl -s -H "Content-Type: application/json" https://beta-api.ambita.com:443/authentication/v2/token -d "
{
\"grant_type\": \"refresh_token\",
\"refresh_token\": \"aj274ajd-t1s8-48sk-v5m1-shf64j9bq25a\"
}"
|
The refresh_token is valid for 30 days and should be stored securely and only be used to get new access_token. The refresh token grant_type will also return a new refresh_token, you should replace your existing refresh_token with the new one, the new refresh_token is valid for another 30 days. If the refresh_token expires, you need to authenticate with client, credentials and grant_type password again.
More information about OAuth can be found here: https://www.oauth.com/
How to integrate
...
How to integrate
You want to start with setting up the authentication, go to the Authentication page.
Then you want to find the product you want to order, this is done by looking up the product list for a given municipality, see Get productsProducts. You can also contact support if you are unsure about what product to order, support@ambita.com.Then make sure you are handling push notifications correctly, see Push messages
You also want to know the price of the product you want to order and in most cases the price will be available on the product, but in the case of ordering a product with custom order data like a map product the price can differ based on the order data, so you should get the price as described in Prices.
Next you want to create an order, this is described in Create an orderOrders.
Then make sure you are handling push notifications correctly, see Push Messages.
When you have created the order, you should then wait for push messages. We recommend to put push messages on a queue and process them sequentially. What to do with the different statuses is described in the Push messagesMessages, but for UPDATE and FINISHED, there is a small difference to what should be done.
...
Use the
orderIdand get the order from our API described in Get orderin OrdersLoop through assets and do necessary actionsFiles , files can occur on both order level and order line level.
Example (provided in JavaScript)
Code Block language js fetch('https://beta-api.ambita.com/kode/v1/orders/:orderId') .then(response => { response.orders.forEach(order => { if (order.assets.length > 0) { // loop through order assets and do necessary actions } order.orderLines.forEach(orderLine => { if (orderLine.assets.length > 0) { // loop through order line assets and do necessary actions } }); }); });Delete or save the file
Response from
https://beta-api.ambita.com/kode/v1/orders/:orderIdCode Block language json { "id": 1234567, "status": "PROGRESS", ... "orders": [ { "id": 1234567, "supplierName": "Infoland Kommune - demo", "assets": [ ... ], ... "orderLines": [ { "id": 12345678, "assets": [ ... ]Take a look at the Get delivered files sectionDelivered Files section, the id of the asset will be unique and should be stored in your system. Use this id as a reference to check if you have downloaded the asset before, this way you won’t end up with duplicates. You should also check the status of the asset and delete the file if it has status
DELETED.
Create an order
To create an order, you need to use the access_token that you previously obtained.
Take a look at our Swagger documentation for the API here: Swagger
Send a POST request to https://beta-api.ambita.com/kode/v1/orders/cadastre
Example request
| Code Block |
|---|
curl -s \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ej577asf-a5k6-42yq-a3a2-fh03hb8cb58c" \
https://beta-api.ambita.com/kode/v1/orders/cadastre -d "
{
\"deliveryInformation\": {
// delivery information object
},
\"orderData\": {
\"address\": \"Infoveien 1, 9999 Infoland\",
\"cadastre\": \"9999-1-1-0-0\"
},
\"products\": [
{
\"code\": \"WI99990033\"
}
],
\"reference\": \"some-reference\",
\"technicalReference\": \"some-technical-reference\"
}"
|
JSON body structure
...
Property
...
Description
...
deliveryInformation*
...
Object that includes information related to delivery of the products, see section below
...
orderData
...
Order data required to order the products specified which will differ based on the type of product being ordered between cadastre, share, map products, see section below
...
reference
...
This reference is used to connect multiple orders to one reference, usually an assignment key and commonly used for billing reference
...
technicalReference*
...
This reference is used to reference an order in our system, to a unique id in your system, good for debugging and lookups
...
products
...
Array of objects, see section below
* indicates optional fields
deliveryInformation object
...
Property
...
Description
...
address*
...
Address line
...
address2*
...
Address line 2
...
address3*
...
Address line 3
...
alias*
...
Alias
...
companyName*
...
Company name
...
email*
...
...
name*
...
Name
...
phone*
...
Phone
...
postalCode*
...
Postal code
* indicates optional fields
orderData object
...
Property
...
Description
...
For ordering cadastre products, see example below
...
address
...
Important to use this format {Street address}, {Postal code} {Postal office}, for example, Infoveien 1, 9999 Infoland
...
cadastre
...
Cadastre should always include all required parts {Kommunenummer}-{Gårdsnummer}-{Bruksnummer}-{Festenummer}-{Seksjonsnummer}, for example, 0301-100-10-0-0
...
For ordering share products, see example below
...
organizationNumber
...
Organization number
...
shareNumber
...
Share number
...
For ordering map product, see example below
...
geometry
...
A closed GeoJSON polygon specified in ETRS89 / UTM zone 33N or ETRS89 / UTM zone 32N
...
spatialReference
...
Spatial reference the geometry is specified in either 25833 or 25832
Example cadastre products orderData
| Code Block |
|---|
"orderData": {
"address": "Infoveien 1, 9999 Infoland",
"cadastre": "9999-1-1-0-0"
} |
Example share products orderData
| Code Block |
|---|
"orderData": {
"organizationNumber": 988424587,
"shareNumber": 136
} |
Example map products orderData
| Code Block |
|---|
"orderData": {
"geometry": {
"type": "Polygon",
"coordinates": [[
[679906.435383017,7741056.419552005],
[679906.4572162632,7742527.458934937],
[681832.6049002217,7742527.507026337],
[681832.6139410603,7741056.365899973],
[679906.435383017,7741056.419552005]
]]
},
"spatialReference": "25833"
} |
products array of objects
...
Property
...
Description
...
code
...
Use product API to find correct product codes in given municipality
...
data*
...
Additional data required to order specific products that varies based on a product, see example below
* indicates optional fields
Example map products array with additional data
| Code Block |
|---|
"products": [
{
"code": "WI54016101",
"data": {
"format": "UTM"
}
}
] |
Example response
| Code Block |
|---|
{
"id": 1664984,
"status": "NEW",
"priceNet": 0,
"priceVat": 0,
"dateOrdered": "2021-01-28T09:10:15+0100",
"dateStatus": "2021-01-28T09:10:15+0100",
"orders": [
{
"id": 2640649,
"supplierName": "Tromsø kommune",
"user": "Test User",
"technicalReference": null,
"orderLines": [
{
"id": 11603164,
"status": {
"code": "NEW",
"name": "New order. Has not been processed yet."
},
"product": "WI54016101",
"productName": "Basiskart som vektordata",
"productType": {
"code": "0",
"name": "NORMAL"
},
"mediaType": "Datafil",
"delivery": "Elektronisk",
"priceNet": 0,
"priceVat": 0
}
]
}
]
} |
Get products
To get products, you need to use the access_token that you previously obtained.
Send a GET request to https://beta-api.ambita.com/kode/v1/products?municipality={municipalityCode}
Take a look at our Swagger documentation for the API here: Swagger
Example request
| Code Block |
|---|
curl -s \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ej577asf-a5k6-42yq-a3a2-fh03hb8cb58c" \
https://beta-api.ambita.com/kode/v1/products?municipality=9999
|
Example response
Get order
To get an order, you need to use the access_token that you previously obtained.
Send a GET request to https://beta-api.ambita.com/kode/v1/orders/1234567
Take a look at our Swagger documentation for the API here: Swagger
Example request
| Code Block |
|---|
curl -s \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ej577asf-a5k6-42yq-a3a2-fh03hb8cb58c" \
https://beta-api.ambita.com/kode/v1/orders/1234567
|
Example response
Push messages
In order for us to notify your system about events on an order, you need to provide a callback URL, send this to support@ambita.com
When there is an event on an order, a push message is sent to your callback URL.
These are the statuses that can be pushed to your system
...
Status
...
Description
...
NEW
...
This status is the same as an order confirmation email, it confirms that our order system has received the order and is ready to process the order
...
UPDATED
...
This status is sent when a new file has arrived and you should get the new file. NB! This status can occur after an order is finished
...
FINISHED
...
This status is sent when an order is set to finished, you should check if you have received all the files
...
CANCELLED
...
This status is sent when the order is cancelled, you should delete the files that you have received on this order
...
REFUNDED
...
This status is sent when the order is refunded, you should delete the files that you have received on this order
Example request body
Get delivered files
Here you can find information about assets in our API
Asset object
| Code Block |
|---|
{
"name": "The-exact-name-of-the-file.pdf",
"filename": "More-descriptive-name-of-the-file.pdf",
"downloadUrl": "https://beta-api.ambita.com/shopping/v2/assets/d2f48dk9d267a86d2858244d0c2c1937",
"assetStatus": "OK",
"productCategory": "PRODUCT_UTEN_KATEGORI",
"id": "d2f48dk9d267a86d2858244d0c2c1937"
}
|
...
Property
...
Description
...
name
...
The name of the file that is uploaded to our system
...
filename
...
A descriptive filename that we create based on product name
...
downloadUrl
...
The URL to where you can download the file
...
assetStatus
...
The status of the asset, see section below
...
productCategory
...
The category of the asset, can be used to categorize files or cost, see section below
...
id
...
Unique id for each asset
Asset status
...
Status
...
Description
...
OK
...
The asset is available and can be downloaded
...
DELETED
...
The asset is deleted and is no longer available, you should remove the file from your system
Product categories
Available product categories
...
Product category
...
PRODUKT_UTEN_KATEGORI
...
KOMMUNAL_INFORMASJON
...
PLAN_KART_REGULERING
...
FERDIGATTEST_OG_MIDLERTIDIG_BRUKSTILLATELSE
File types
Most of the files are PDFs, but we also deliver other file types, these are the most common types:
...
...
.txt
...
.xlsx, .xls, .csv
...
.jpg, .png
...
.sos, .kof, .dxf, .dvg, .sketchup
...
Distributor Messages
You should implement handling of these messages, see Distributor Messages for more info.