# Authentication, input and response

## Assess the full potential of the **Satellite Roof Scan API** by understanding the key parameters and response.

<mark style="color:green;">`POST`</mark> `https://api.altum.ai/satellite-roof-scan`&#x20;

The endpoint allows you to interact with the Solar Panel API by sending specific queries, such as postal codes, to retrieve detailed real estate data. You can find the full endpoint above.

### Query Parameters&#x20;

| Parameter       | Type      | Description                                                                                                  |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| `postcode`      | `string`  | zip code in six character format e.g. 1234AB                                                                 |
| `housenumber`   | `string`  | house number of the object e.g. 1                                                                            |
| `huisletter`    | `string`  | addition to the house number e.g. A                                                                          |
| `roof_geometry` | `boolean` | The polygon shape of the selected roof; if false, it skips geometry and only performs image-based detection. |
| `image_source`  | `string`  | Specifies where the imagery comes from (auto, **pdok**,**esri**, or **google\_maps**).                       |

{% hint style="info" %}
Note:&#x20;

* The **huisletter** is an **optional** field, you can leave it empty ("") otherwise all fields are **required**.
* Some roof geometries are not always available.
* Google Maps Services are **temporarily disabled**.
* You can switch the image source between **pdok**, **esri**,or **auto** (default).
  {% endhint %}

### Headers

<table><thead><tr><th width="152">Name</th><th width="145">Type</th><th>Description</th></tr></thead><tbody><tr><td>Content-Type</td><td>string</td><td>application/json</td></tr><tr><td>x-api-key<mark style="color:red;">*</mark></td><td>string</td><td>Unique API key from Altum. Obtain one via Mopsus (https://mopsus.altum.ai)</td></tr></tbody></table>

### Response

Upon a successful `POST` request, the API returns a `200 OK` status with a JSON object containing the results.

**Example Complete Output**

| Field                 | Type      | Description                                                                                                                                        |
| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `postcode`            | `string`  | zip code in six character format e.g. 1234AB                                                                                                       |
| `housenumber`         | `string`  | house number of the object e.g. 1                                                                                                                  |
| `huisletter`          | `string`  | addition to the house number e.g. A                                                                                                                |
| `imagery_source`      | `string`  | Source of the aerial image used.                                                                                                                   |
| `annotated_image_url` | `string`  | A public URL to the image with detected solar panels drawn on it.                                                                                  |
| `imagery_date`        | `date`    | Date of the aerial image was captured.                                                                                                             |
| `num_panels_detected` | `integer` | The total number of solar panels (or other detected objects) found.                                                                                |
| `detections`          | `array`   | An array of JSON objects, with each object describing a detected solar panel, including its label, confidence score, and bounding box coordinates. |

### Request body

A valid `POST` request body would look like this:

```
{
  "postcode": "4624AD",
  "housenumber": "4",
	"huisletter": "",
  "roof_geometry": true,
  "image_source": "auto" 
}
```

### Output <a href="#id-5.-output" id="id-5.-output"></a>

Upon a successful `POST` request, the API returns a `200 OK` status with a JSON object containing the results.

**Example Complete Output**

```
{
	"postcode": "4624AD",
	"housenumber": "4",
	"huisletter": "",
	"houseaddress": "4624AD-4-",
	"imagery_source": "PDOK Aerial RGB (Open), Current Ortho 25cm RGB",
	"annotated_image_url": "https://altum-gis.s3.eu-west-1.amazonaws.com/solar_panels/4624AD-4-_6bec97ef.png",
	"imagery_date": "2025",
	"num_panels_detected": 8,
	"detections": [
		{
			"label": "solar",
			"confidence": 0.69,
			"bbox": {
				"x1": 342,
				"y1": 656,
				"x2": 525,
				"y2": 687,
				"width": 183,
				"height": 31
			}
    },
    ... (more detections)
  ]
}
```

<figure><img src="/files/7QxFF6UvQJGlYr6VHYuR" alt="" width="375"><figcaption></figcaption></figure>

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

```
{
	"postcode": "4624AD",
	"housenumber": "4",
	"huisletter": "",
	"houseaddress": "4624AD-4-",
	"imagery_source": "PDOK Aerial RGB (Open), Current Ortho 25cm RGB",
	"annotated_image_url": "https://altum-gis.s3.eu-west-1.amazonaws.com/solar_panels/4624AD-4-_6bec97ef.png",
	"imagery_date": "2025",
	"num_panels_detected": 8,
	"detections": [
		{
			"label": "solar",
			"confidence": 0.69,
			"bbox": {
				"x1": 342,
				"y1": 656,
				"x2": 525,
				"y2": 687,
				"width": 183,
				"height": 31
			}
    },
    ... (more detections)
  ]
}
```

{% endtab %}

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

```
{
	The request was invalid.
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```
Failed to scrape image for BAG ID: {bagid}. 
This might mean the BAG ID was not found in the database or there was an issue with PDOK API.


```

{% endtab %}

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

```
{
	"message": "An unexpected server error occurred."
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.altum.ai/english/sustainability/satellite-roof-scan/authentication-input-and-response.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.