API tutorial - Revision history

Frank@tygron.nl at 07:52, 9 June 2026

2026-06-09T07:52:06Z

← Older revision		Revision as of 07:52, 9 June 2026
Line 8:		Line 8:

	==Introduction to the API==		==Introduction to the API==
	The {{software\|server}} offers access via an API, allowing for external applications to interact with and use the {{software\|server}}. The API is an integral part of the functioning of the {{software}}, in that the default {{software\|client}} app uses it as well. This means the API can allow you to do anything that the {{software\|client}} app allows you to do as well.		The {{software server}} offers access via an API, allowing for external applications to interact with and use the {{software server}}. The API is an integral part of the functioning of the {{software}}, in that the default {{software client}} app uses it as well. This means the API can allow you to do anything that the {{software client}} app allows you to do as well.

	The API can be used to:		The API can be used to:
Line 14:		Line 14:
	* Automate menial and complex tasks		* Automate menial and complex tasks
	* Integrate the output of external applications in projects and sessions automatically		* Integrate the output of external applications in projects and sessions automatically
	* Integrate the {{software\|server}} with an existing process chain		* Integrate the {{software server}} with an existing process chain

	Overall, the API is split into two separate sections, a root API and a session API. The root API is for access to the {{software\|server}} in general, and can be used to access user information or domain information, start and save projects, and manage access rights. The session API is for interactions with a specific session, modifying the data in it, or obtaining results as calculated in the Session.		Overall, the API is split into two separate sections, a root API and a session API. The root API is for access to the {{software server}} in general, and can be used to access user information or domain information, start and save projects, and manage access rights. The session API is for interactions with a specific session, modifying the data in it, or obtaining results as calculated in the Session.

	The API can be accessed via a web browser, allowing for easy inspection of the data and options.		The API can be accessed via a web browser, allowing for easy inspection of the data and options.
Line 374:		Line 374:
	Switch to the JSON format. Note that more information is available.		Switch to the JSON format. Note that more information is available.

	Just like with the session API, the root API allows you to fire events as instruction to the {{software\|server}}. Go back to the "/api/", and go to "Fire Service Event". Next, select "IO" (which stands for "IO Service Events").		Just like with the session API, the root API allows you to fire events as instruction to the {{software server}}. Go back to the "/api/", and go to "Fire Service Event". Next, select "IO" (which stands for "IO Service Events").

	Select the event "GET_DOMAIN_STARTABLE_PROJECTS". Enter the name of your domain, and fire the event. The response will be a list of all projects which can be started by your user in your domain.		Select the event "GET_DOMAIN_STARTABLE_PROJECTS". Enter the name of your domain, and fire the event. The response will be a list of all projects which can be started by your user in your domain.
Line 951:		Line 951:
	All tasks can be performed via the API. However, for some tasks the appropriate events and their parameters may not be directly apparent.		All tasks can be performed via the API. However, for some tasks the appropriate events and their parameters may not be directly apparent.

	As a general rule of thumb, to perform any task via the API, it can be beneficial to perform the task in the {{software\|client}} of the {{software}} first, and take note of the kind of steps taken to complete the full task.		As a general rule of thumb, to perform any task via the API, it can be beneficial to perform the task in the {{software client}} of the {{software}} first, and take note of the kind of steps taken to complete the full task.

	===Use GeoTIFF as heightmap===		===Use GeoTIFF as heightmap===

Maxim@tygron.com: /* Keeping a session alive */

2026-06-05T15:16:44Z

Keeping a session alive

← Older revision		Revision as of 15:16, 5 June 2026
Line 764:		Line 764:
	By default, if a session is not interacted with for 30 minutes, the session is closed automatically. In this context, it can mean any of the following:		By default, if a session is not interacted with for 30 minutes, the session is closed automatically. In this context, it can mean any of the following:
	* Firing an event, using a POST request.		* Firing an event, using a POST request.
	* Polling the "/poll/" endpoint (or ~~old~~ "/update/"), using a POST request.		* Polling the "/poll/" endpoint (or deprecated endpoint "/update/"), using a POST request.
	* Accessing the web interface, or any part of it.		* Accessing the web interface, or any part of it.
	* Executing a query.		* Executing a query.

Frank@tygron.nl at 14:12, 5 June 2026

2026-06-05T14:12:23Z

← Older revision		Revision as of 14:12, 5 June 2026
Line 888:		Line 888:
	};		};

	fetch(`https://~~development~~.tygron.com/api/session/event/editorindicator/set_excel/?`, options)		fetch(`https://engine.tygron.com/api/session/event/editorindicator/set_excel/?`, options)
	.then(response => response.text())		.then(response => response.text())
	.then(console.log, console.error);		.then(console.log, console.error);
Line 903:		Line 903:
	body: JSON.stringify(['AVG'])		body: JSON.stringify(['AVG'])
	};		};
	fetch(`https://~~development~~.tygron.com/api/session/event/editoroverlay/add/?`, options)		fetch(`https://engine.tygron.com/api/session/event/editoroverlay/add/?`, options)
	.then(response => response.text())		.then(response => response.text())
	.then(console.log, console.error);		.then(console.log, console.error);
Line 977:		Line 977:
	First create a function override.		First create a function override.
	{{code\|1=let token = 'API_TOKEN';		{{code\|1=let token = 'API_TOKEN';
	~~var~~ FUNCTION_ID=$FUNCTION_ID;		let FUNCTION_ID=$FUNCTION_ID;
	~~$.ajax(~~{		let options = {
	~~url~~:~~'/api/session/event/editorfunctionoverride/add/?token='+token~~,		method: "POST",
	~~method~~: ~~'POST',~~		headers: { "Content-Type": "application/json", "Authorization": "Bearer " + token },
	~~contentType~~: 'application/json',		body: JSON.stringify([FUNCTION_ID])
	~~datatype~~: ~~'json'~~,		};
	~~data~~: JSON.stringify([FUNCTION_ID])		fetch(`https://development.tygron.com/api/session/event/editorfunctionoverride/add/?`, options)
	});		.then(response => response.text())
			.then(console.log, console.error);
	}}		}}
	This will create a new function override, with the same ID as the function for which an override was created. Next, the values of that function override can be modified.		This will create a new function override, with the same ID as the function for which an override was created. Next, the values of that function override can be modified.
Line 990:		Line 991:
	To change a function value:		To change a function value:
	{{code\|1=let token = 'API_TOKEN';		{{code\|1=let token = 'API_TOKEN';
	~~var~~ FUNCTION_OVERRIDE_ID=$FUNCTION_ID;		let FUNCTION_OVERRIDE_ID=$FUNCTION_ID;
	~~var~~ FUNCTION_VALUE=$FUNCTION_VALUE;		let FUNCTION_VALUE=$FUNCTION_VALUE;
	~~var~~ newValue = $newValue;		let newValue = $newValue;
	~~$.ajax(~~{		let options = {
	~~url~~:~~'/api/session/event/editorfunctionoverride/set_function_value/?token='+token~~,		method: "POST",
	~~method~~: ~~'POST',~~		headers: { "Content-Type": "application/json", "Authorization": "Bearer " + token },
	~~contentType~~: 'application/json',		body: JSON.stringify([FUNCTION_OVERRIDE_ID, FUNCTION_VALUE, newValue])
	~~datatype~~: ~~'json'~~,		};
	~~data~~: JSON.stringify([FUNCTION_OVERRIDE_ID, FUNCTION_VALUE, newValue])		fetch(`https://development.tygron.com/api/session/event/editorfunctionoverride/set_function_value/?`, options)
	});		.then(response => response.text())
			.then(console.log, console.error);
	}}		}}
	To add or change an attribute:		To add or change an attribute:
	{{code\|1=let token = 'API_TOKEN';		{{code\|1=let token = 'API_TOKEN';
	~~var~~ FUNCTION_OVERRIDE_ID=$FUNCTION_ID;		let FUNCTION_OVERRIDE_ID=$FUNCTION_ID;
	~~var~~ ATTRIBUTE_NAME=$ATTRIBUTE_NAME;		let ATTRIBUTE_NAME=$ATTRIBUTE_NAME;
	~~var~~ newValue = $newValue;		let newValue = $newValue;
	~~$.ajax(~~{		let options = {
	~~url~~:~~'/api/session/event/editorfunctionoverride/set_attribute/?token='+token~~,		method: "POST",
	~~method~~: ~~'POST',~~		headers: { "Content-Type": "application/json", "Authorization": "Bearer " + token },
	~~contentType~~: 'application/json',		body: JSON.stringify([FUNCTION_OVERRIDE_ID, ATTRIBUTE_NAME, newValue])
	~~datatype~~: ~~'json'~~,		};
	~~data~~: JSON.stringify([FUNCTION_OVERRIDE_ID, ATTRIBUTE_NAME, newValue~~, null~~])		fetch(`https://development.tygron.com/api/session/event/editorfunctionoverride/set_attribute/?`, options)
	});		.then(response => response.text())
			.then(console.log, console.error);
	}}		}}
	If a function value or attribute is sought for a specific building, the {{software}} will first look at the building itself. If that building does not have that value, a function override is consulted (if it exists). If that one too does not have the appropriate value, the function it is based on is consulted. If at any point the function was duplicated from another function, that original function may be consulted as well, if the duplicated function's override does not have its own value set.		If a function value or attribute is sought for a specific building, the {{software}} will first look at the building itself. If that building does not have that value, a function override is consulted (if it exists). If that one too does not have the appropriate value, the function it is based on is consulted. If at any point the function was duplicated from another function, that original function may be consulted as well, if the duplicated function's override does not have its own value set.

Frank@tygron.nl: /* Use GeoTIFF as heightmap */

2026-06-05T13:52:17Z

Use GeoTIFF as heightmap

← Older revision		Revision as of 13:52, 5 June 2026
Line 958:		Line 958:
	After uploading the GeoTIFF, the map must be modified based on the GeoTIFF.		After uploading the GeoTIFF, the map must be modified based on the GeoTIFF.
	{{code\|1=let token = 'API_TOKEN';		{{code\|1=let token = 'API_TOKEN';
	~~var~~ GEOTIFF_ID=$GEOTIFF_ID;		let GEOTIFF_ID=$GEOTIFF_ID;
	~~$.ajax(~~{		let options = {
	~~url~~:~~'/api/session/event/editormap/set_height_geotiff/?token='+token~~,		method: "POST",
	~~method~~: ~~'POST',~~		headers: { "Content-Type": "application/json", "Authorization": "Bearer " + token },
	~~contentType~~: 'application/json',		body: JSON.stringify([GEOTIFF_ID])
	~~datatype~~: ~~'json'~~,		};
	~~data~~: JSON.stringify([GEOTIFF_ID])		fetch(`https://engine.tygron.com/api/session/event/editormap/set_height_geotiff/?`, options)
	});		.then(response => response.text())
			.then(console.log, console.error);
	}}		}}

Frank@tygron.nl: /* Downloading a GeoTIFF */

2026-06-05T13:46:16Z

Downloading a GeoTIFF

← Older revision		Revision as of 13:46, 5 June 2026
Line 898:		Line 898:

	{{code\|1=let token = 'API_TOKEN';		{{code\|1=let token = 'API_TOKEN';
	~~$.ajax(~~{		let options = {
	~~url~~:~~'/api/session/event/editoroverlay/add/?token='+token~~,		method: "POST",
	~~method~~: ~~'POST',~~		headers: { "Content-Type": "application/json", "Authorization": "Bearer " + token },
	~~contentType~~: 'application/json',		body: JSON.stringify(['AVG'])
	~~datatype~~: ~~'json'~~,		};
	~~data~~: JSON.stringify(['AVG'])		fetch(`https://development.tygron.com/api/session/event/editoroverlay/add/?`, options)
	});		.then(response => response.text())
			.then(console.log, console.error);
	}}		}}

Frank@tygron.nl: /* Uploading assets */

2026-06-05T13:34:24Z

Uploading assets

← Older revision		Revision as of 13:34, 5 June 2026
Line 882:		Line 882:
	var INDICATOR_ID=$INDICATOR_ID;		var INDICATOR_ID=$INDICATOR_ID;
	var EXCEL_ID=$EXCEL_ID;		var EXCEL_ID=$EXCEL_ID;
	~~$.ajax(~~{		let options = {
	~~url~~:~~'/api/session/event/editorindicator/set_excel/?token='+token~~,		method: "POST",
	~~method~~: ~~'POST',~~		headers: { "Content-Type": "application/json", "Authorization": "Bearer " + token },
	~~contentType~~: 'application/json',		body: JSON.stringify([INDICATOR_ID, EXCEL_ID])
	~~datatype~~: ~~'json'~~,		};
	~~data~~: JSON.stringify([INDICATOR_ID, EXCEL_ID])
	});		fetch(`https://development.tygron.com/api/session/event/editorindicator/set_excel/?`, options)
			.then(response => response.text())
			.then(console.log, console.error);
	}}		}}
	{{page break}}		{{page break}}

Frank@tygron.nl: /* Saving */

2026-06-05T13:22:12Z

Saving

← Older revision		Revision as of 13:22, 5 June 2026
Line 686:		Line 686:

	fetch(`https://engine.tygron.com/api/event/io/save_project/?`, options)		fetch(`https://engine.tygron.com/api/event/io/save_project/?`, options)
	.then(response => response.text())		.then(response => response.text())

	.then(console.log, console.error);		.then(console.log, console.error);
	}}		}}

Frank@tygron.nl: /* Starting project generation at location */

2026-06-05T13:21:49Z

Starting project generation at location

← Older revision		Revision as of 13:21, 5 June 2026
Line 589:		Line 589:

	fetch(`https://engine.tygron.com/api/session/event/editor/start_map_creation/?`, options)		fetch(`https://engine.tygron.com/api/session/event/editor/start_map_creation/?`, options)
	.then(response => response.text())		.then(response => response.text())

	.then(console.log, console.error);		.then(console.log, console.error);
	}}		}}

Frank@tygron.nl: /* Sessions */

2026-06-05T13:21:34Z

Sessions

← Older revision		Revision as of 13:21, 5 June 2026
Line 422:		Line 422:
	.then(response => response.text())		.then(response => response.text())
	.then(console.log, console.error);		.then(console.log, console.error);
	~~</script>~~
	}}		}}
	Notice that the server takes a few seconds to respond, and then responds with a session ID. This means a new session has started on the server. Specifically, the project has started as a session in		Notice that the server takes a few seconds to respond, and then responds with a session ID. This means a new session has started on the server. Specifically, the project has started as a session in

Frank@tygron.nl: /* Requesting updates manually */

2026-06-05T13:21:15Z

Requesting updates manually

← Older revision		Revision as of 13:21, 5 June 2026
Line 244:		Line 244:

	fetch(`https://engine.tygron.com/api/session/items/areas/version/?f=JSON`, options)		fetch(`https://engine.tygron.com/api/session/items/areas/version/?f=JSON`, options)
	.then(response => response.text())		.then(response => response.text())

	.then(console.log, console.error);		.then(console.log, console.error);
	}}		}}