Authentication, input and response

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

POST https://api.altum.ai/satellite-roof-scan

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

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).

Note:

• 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).

Headers

Name	Type	Description
Content-Type	string	application/json
x-api-key*	string	Unique API key from Altum. Obtain one via Mopsus (https://mopsus.altum.ai)

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

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)
  ]
}

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)
  ]
}

400: Bad Request Unsuccessful response

404 Not Found

500: Internal Server Error Service is not available and/or down