# Authentication, input and response

## WOZ API methods

* **POST** to receive WOZ value for a single address
* **GET** WOZ value for a BAG ID

## Post object data to receive WOZ values

<mark style="color:green;">`POST`</mark> `https://api.altum.ai/woz`

This endpoint allows you to get the latest WOZ values from our database. A POST request requires a body parameter(Address).

#### Headers

| Name                                        | Type   | Description                                                                 |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------- |
| Content-Type                                | string | application/json                                                            |
| x-api-key<mark style="color:red;">\*</mark> | string | Unique API Key from Altum. Create one via Mopsus(<https://mopsus.altum.ai>) |

#### Request Body

| Name                                          | Type    | Description                                                                                                                        |
| --------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| postcode<mark style="color:red;">\*</mark>    | string  | Zipcode of the object                                                                                                              |
| housenumber<mark style="color:red;">\*</mark> | string  | House number of the object                                                                                                         |
| addition                                      | string  | House number addition                                                                                                              |
| index                                         | boolean | Use 1 to add an "IndexedValue" to the latest available WOZ value indexed with the Kadaster index to the current month. Default = 0 |
| cache                                         | boolean | Use 0 to override fetching from cache and perform a live request. Default = 1                                                      |

{% tabs %}
{% tab title="401: Unauthorized No access" %}

```
{
    'Output': 'Please use https://api.altum.ai or visit https://mopsus.altum.ai to make your request.'
}
```

{% endtab %}

{% tab title="403: Forbidden Forbidden" %}

```
{
	"message": "Missing Authentication Token"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Service is not available and/or down" %}

```
{
	"message": "Internal server error"
}
```

{% endtab %}

{% tab title="200: OK Successful response" %}

```
{
	"Output": {
		"BagID": "499010002023718",
		"PostCode": "2771DS",
		"HouseNumber": "87",
		"HouseAddition": null,
		"HouseAddress": "2771DS-87-",
		"City": "Boskoop",
		"Street": "Zuidkade",
		"HouseType": "woonfunctie",
		"BuildYear": 1961,
		"OuterSurfaceArea": 1605,
		"Longitude": 4.65808526945334,
		"Latitude": 52.068393816655316,
		"WOZ-source_date": "2023-03-21",
		"wozvalue": [
			{
				"Date": "01-01-2022",
				"Value": "630000",
				"IndexedValue": "644942"
			},
			{
				"Date": "01-01-2021",
				"Value": "551000"
			},
			{
				"Date": "01-01-2020",
				"Value": "518000"
			},
			{
				"Date": "01-01-2019",
				"Value": "498000"
			},
			{
				"Date": "01-01-2018",
				"Value": "490000"
			},
			{
				"Date": "01-01-2017",
				"Value": "469000"
			},
			{
				"Date": "01-01-2016",
				"Value": "430000"
			}
		]
	}
}
```

{% endtab %}

{% tab title="400: Bad Request Unsuccessful response" %}

```
{
  "detail": {
    "Output": "The combination of postcode, house number and house addition  does not exist or have no WOZ."
  }
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Wrong input format" %}

```
{
  "detail": [
    {
      "loc": [
        "body",
        "postcode"
      ],
      "msg": "Unsupported postcode length, it should be six.",
      "type": "value_error"
    }
  ]
}
```

{% endtab %}

{% tab title="429: Too Many Requests Limit exceeded" %}

```
API key limit exceeded
```

{% endtab %}
{% endtabs %}

## GET WOZ Values with BAGID request

<mark style="color:blue;">`GET`</mark> `https://api.altum.ai/woz?bag_id={bag_id}`

This endpoint responds with the latest WOZ values from our database. The GET Method requires a query parameter(bag\_id) with the value being the actual 16-character BAGID.

#### Query Parameters

| Name                                      | Type   | Description                                      |
| ----------------------------------------- | ------ | ------------------------------------------------ |
| bag\_id<mark style="color:red;">\*</mark> | string | <p>16 digits BAG ID</p><p>"0402010001567022"</p> |

#### Headers

| Name                                        | Type   | Description                                                          |
| ------------------------------------------- | ------ | -------------------------------------------------------------------- |
| Content-Type                                | string | application/json                                                     |
| x-api-key<mark style="color:red;">\*</mark> | string | API Key from Altum. Create one via Mopsus(<https://mopsus.altum.ai>) |

{% tabs %}
{% tab title="200: OK Successful response" %}

```
{
  "Output": {
    "BagID": "0622010000065935",
    "PostCode": "3136KZ",
    "HouseNumber": "832",
    "HouseAddition": null,
    "HouseAddress": "3136KZ-832-",
    "City": "Vlaardingen",
    "Street": "Aalscholverlaan",
    "HouseType": "woonfunctie",
    "BuildYear": 1969,
    "OuterSurfaceArea": 1412,
    "Longitude": 4.350730676835097,
    "Latitude": 51.93255387951979,
    "WOZ-source_date": "2020-12-22",
    "wozvalue": [
      {
        "Date": "01-01-2019",
        "Value": 157000
      },
      {
        "Date": "01-01-2018",
        "Value": 133000
      },
      {
        "Date": "01-01-2017",
        "Value": 122000
      },
      {
        "Date": "01-01-2016",
        "Value": 122000
      },
      {
        "Date": "01-01-2015",
        "Value": 122000
      },
      {
        "Date": "01-01-2014",
        "Value": 132000
      }
    ]
  }
}
```

{% endtab %}

{% tab title="400: Bad Request Unsuccessful response" %}

```
{
	"detail": [
		{
			"loc": [
				"query",
				"bag_id"
			],
			"msg": "ensure this value has at least 16 characters",
			"type": "value_error.any_str.min_length",
			"ctx": {
				"limit_value": 16
			}
		}
	]
}
```

{% endtab %}

{% tab title="401: Unauthorized No access" %}

```
{
    'Output': 'Please use https://api.altum.ai or visit https://mopsus.altum.ai to make your request.'
}
```

{% endtab %}

{% tab title="403: Forbidden Forbidden" %}

```
{
	"message": "Missing Authentication Token"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Service is not available and/or down" %}

```
{
	"message": "Internal server error"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Wrong input format" %}

```
{
  "detail": [
    {
      "loc": [
        "body",
        "postcode"
      ],
      "msg": "Unsupported postcode length, it should be six.",
      "type": "value_error"
    }
  ]
}
```

{% endtab %}

{% tab title="429: Too Many Requests Limit exceeded" %}

```
API key limit exceeded
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
For **POST** requests: set cache to 0 to fetch fresh, real-time values instead from cache as source.\
Note: this might impact load time.
{% endhint %}

## FREE Ping for availability

## Post object data to receive availability of WOZ values

<mark style="color:green;">`POST`</mark> `https://api.altum.ai/woz/ping`

This endpoint allows you to get the availability of the latest WOZ values from our database. A POST request requires a body parameter (Address).

#### Headers

| Name                                        | Type   | Description                                                          |
| ------------------------------------------- | ------ | -------------------------------------------------------------------- |
| Content-Type                                | string | application/json                                                     |
| x-api-key<mark style="color:red;">\*</mark> | string | API Key from Altum. Create one via Mopsus(<https://mopsus.altum.ai>) |

#### Request Body

| Name                                          | Type    | Description                                                                                                                        |
| --------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| postcode<mark style="color:red;">\*</mark>    | string  | Zipcode of the object                                                                                                              |
| housenumber<mark style="color:red;">\*</mark> | string  | House number of the object                                                                                                         |
| addition                                      | string  | House number addition                                                                                                              |
| index                                         | boolean | Use 1 to add an "IndexedValue" to the latest available WOZ value indexed with the Kadaster index to the current month. Default = 0 |
| cache                                         | boolean | Use 0 to override fetching from cache and perform a live request. Default = 1                                                      |

{% tabs %}
{% tab title="401: Unauthorized No access" %}

```
{
    'Output': 'Please use https://api.altum.ai or visit https://mopsus.altum.ai to make your request.'
}
```

{% endtab %}

{% tab title="403: Forbidden Forbidden" %}

```
{
	"message": "Missing Authentication Token"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Service is not available and/or down" %}

```
{
	"message": "Internal server error"
}
```

{% endtab %}

{% tab title="200: OK Successful response" %}

```
{ 
        "Output": "WOZ data for 1616EG-130- is available.", 
        "Latest Date": "01-01-2021" 
} 
```

{% endtab %}

{% tab title="422: Unprocessable Entity Wrong input format" %}

```
{
  "detail": [
    {
      "loc": [
        "body",
        "postcode"
      ],
      "msg": "Unsupported postcode length, it should be six.",
      "type": "value_error"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Request body

#### Example request

```
{
  "postcode": "2771DS",
  "housenumber": "87",
  "addition": "",
  "index": 1,
  "cache": 0
}
```

## Request query

#### Example request

```
https://api.altum.ai/woz?bag_id=0402010001567022
```