Perform your first API call

The goal of this page is to give examples on how to perform an API call in your application.

Tip! Use the following applications

Anchor link to the article.

OpenAPI specification

Perform a GET request to the API endpoint of choice with '/openapi' amended to retrieve the OpenAPI specification for the given API. Example:

OpenAPI specification for AVM API

GET https://api.altum.ai/avm/openapi

{
	"openapi": "3.0.2",
	"info": {
		"title": "AVM API",
		"description": "Predicts the transaction value for a given house address.",
		"version": "2.0"
	},
	"paths": {
		"/predict": {
			"post": {
				"tags": [
					"AVM API"
				],
				"summary": "Displays the AVM data as well as the prediction.",
				"operationId": "output_predict_post",
				"requestBody": {
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/AVM"
							}
						}
					},
					"required": true
				},
				"responses": {
					"200": {
						"description": "Prediction for the given house address.",
						"content": {
							"application/json": {
								"schema": {},
								"example": {
									"Output": {
										"BagID": "str",
										"PostCode": "str",
										"HouseNumber": "int",
										"HouseAddition": "str",
										"City": "str",
										"Street": "str",
										"HouseType": "str",
										"BuildYear": "int",
										"InnerSurfaceArea": "int",
										"OuterSurfaceArea": "int",
										"Volume": "int",
										"EnergyLabel": "str",
										"Longitude": "float",
										"Latitude": "float",
										"Rooms": "int",
										"Image": "str",
										"ValuationDate": "int",
										"PriceEstimation": "int",
										"Confidence": "str",
										"AccuracyIndicator": "int or str"
									}
								}
							}
						}
					},
					"400": {
						"description": "The given house address was not found in database.",
						"content": {
							"application/json": {
								"example": [
									"Output: The given house address was not found in database."
								]
							}
						}
					},
					"422": {
						"description": "Validation Error.",
						"content": {
							"application/json": {
								"example": {
									"detail": [
										{
											"loc": [
												"query",
												"housenumber"
											],
											"msg": "ensure this value is greater than 0",
											"type": "value_error.number.not_gt",
											"ctx": {
												"limit_value": 0
											}
										}
									]
								}
							}
						}
					}
				}
			}
		}
	},
	"components": {
		"schemas": {
			"AVM": {
				"title": "AVM",
				"required": [
					"postcode",
					"housenumber"
				],
				"type": "object",
				"properties": {
					"postcode": {
						"title": "Postcode of the given house.",
						"pattern": "^(?!1000|1001|1002|1003|1004|1005|1006|1007|1008|1009|1010)[1-9][0-9]{3}[A-Z]{2}$",
						"type": "string",
						"example": "1234AB"
					},
					"housenumber": {
						"title": "House number of the given house.",
						"exclusiveMinimum": 0.0,
						"type": "integer",
						"example": 1
					},
					"houseaddition": {
						"title": "House addition of the given house.",
						"type": "string",
						"default": ""
					},
					"valuationdate": {
						"title": "Date of evaluation.",
						"type": "string",
						"format": "date",
						"default": "20230410"
					},
					"buildyear": {
						"title": "Buildyear",
						"maximum": 2023.0,
						"minimum": 1800.0,
						"type": "integer"
					},
					"innersurfacearea": {
						"title": "Innersurfacearea",
						"exclusiveMinimum": 0.0,
						"type": "number"
					},
					"outersurfacearea": {
						"title": "Outersurfacearea",
						"exclusiveMinimum": 0.0,
						"type": "number"
					},
					"housetype": {
						"title": "Housetype",
						"enum": [
							"Vrijstaande woning",
							"2 onder 1 kap woning",
							"Geschakelde 2 onder 1 kapwoning",
							"Geschakelde woning",
							"Tussen/rijwoning",
							"Hoekwoning",
							"Eindwoning",
							"Galerijflat",
							"Portiekflat",
							"Corridorflat",
							"Maisonnette",
							"Benedenwoning",
							"Bovenwoning",
							"Portiekwoning"
						],
						"type": "string"
					},
					"energylabel": {
						"title": "Energylabel",
						"enum": [
							"G",
							"F",
							"E",
							"D",
							"C",
							"B",
							"A",
							"A+",
							"A++",
							"A+++",
							"A++++",
							"A+++++"
						],
						"type": "string"
					},
					"image": {
						"title": "Image",
						"enum": [
							0,
							1
						],
						"type": "integer",
						"default": 0
					}
				}
			}
		}
	}
}

Performing a request in Reqbin.com

Go to Reqbin.com and add the endpoint URL in the URL-box. Depending on the API, select a POST or GET request. Be sure to select "DE" or "EXT" as the server for faster processed requests. Add the message / request in the Content tab. Add the x-api-key header for authentication to the Headers tab.

Press "send" to perform the request.

Curl/Bash

#!/bin/bash

curl -X POST https://api.altum.ai/sandbox/avm -H "x-api-key: m2ipzWVV3e9yPU9TduqpY4oZTbcEHCGj31GLVLYB" -H "Content-Type: application/json" --data-binary @- <<DATA
{
   "postcode" : "1234AB",
   "housenumber" : "1"
}
DATA

Performing a request in Insomnia

Download and install the free program Insomnia. Create a new 'Request collection'. Add a 'New Request' (CTRL + N) and gives this request a name. Select POST or GET depending on the API and use JSON for the Body Text when Posting.

Add the endpoint URL of the API behind the POST/GET function into the endpoint URL box. Then add the JSON message to the JSON entry field. Lastly, configure the headers to include the Content-Type and the x-api-key for authentication and press "Send".

curl --request POST \
  --url https://api.altum.ai/sustainability \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: m2ipzWVV3e9yPU9TduqpY4oZTbcEHCGj31GLVLYB' \
  --data '{
  "data": {
    "lock_measures": {
      "lock": [
        "wall_insulation"
      ]
    },
    "max_investment": 20000,
    "gas_usage": 3000,
    "post_code": "2771DS",
    "house_number": "87",
    "target_label": "A",
    "inner_surface_area": 130,
    "inhabitants": 3,
    "replace_boiler": true,
    "heat_pump_allowed": true,
    "search_criteria": 1,
    "search_options": 2,
    "house-type": 1,
    "natural_gas": 0,
    "solar_panels_surface": 1,
    "watt_panels": true,
    "wall_insulation": 1,
    "roof_insulation": 1,
    "floor_insulation": 1,
    "living_room_windows": 1,
    "bedroom_windows": 1,
    "installation": 4,
    "shower": 0,
    "ventilation": 0,
    "solar_panels": 10
  }
}'

Performing a request in Postman

Download the Postman app. Create a new HTTP Request. Select the method GET or POST depending on the API and add the endpoint URL. Set authorization to No Auth.

Add the x-api-key header and API key for authentication. Set the Body to raw and JSON when performing a POST request. Press "Send"