# API References

The Jakartowns JavaScript API enables integration of the Jakartowns digital twin into third-party web applications. The JavaScript script contains the API’s code, including all its functions and methods to manipulate the digital twin.

The API facilitates interaction with the digital twin by providing methods to set the position, rotation, tilt, field of view, and displayed panoramic image.

The API is applied to an HTML container within the web application page.

Once the API is retrieved, the `create_jakartowns` function is available to create an instance of the Jakartowns digital twin in a specific container on the web page.

<details>

<summary><code>window.jakartowns.app.create_jakartowns('#app', options, callback)</code></summary>

This function is responsible for creating the Jakartowns digital twin in the specified container, with the given configuration options, and executes the callback function once the digital twin is ready for use. This allows developers to interact with the digital twin and customize its behavior according to specific needs.

Here’s a detailed explanation of each parameter of this function:

1. `'#app'`: This is the CSS selector of the HTML element where you want to display the digital twin. In this case, the element with the ID "app" will be used as the container for the digital twin.
2. `options`: This is a JavaScript object containing configuration options for the digital twin. These options control whether the digital twin’s header and mini-map are enabled or disabled.
3. `callback`: This is a callback function that is called once the digital twin instance is created and ready for use. The callback function can be defined as an anonymous function (arrow function) that takes a `viewer` parameter. The `viewer` parameter corresponds to the created digital twin instance. You can use this instance to perform specific actions and operations on the digital twin, such as adding listeners for position, rotation, tilt, and FOV update events.

</details>

### Functions to Interact with the Digital Twin

The following functions are available on the `viewer` instance returned in the `create_jakartowns` callback.

#### `viewer.setPosition({ latitude, longitude }, options)`

Sets the digital twin view position on the map using the specified latitude and longitude coordinates.

This function returns a promise resolved with an object containing:

* `uid`: the technical identifier of the selected image
* `distance`: the distance between the requested position and the selected panoramic image
* `nearest`: the GeoJSON feature representing the selected panoramic image
* `features`: the list of panorama candidates returned by the search

Available options:

* `keepPreviousAngles`: keeps the current orientation if set to `true` during the transition (default: false)
* `observerShift`: moves forward or backward in the trajectory with `{ direction: 'forward' | 'backward', steps: number }`
* `dateFilter`: filters images by date, for example `{ date: '2024-05-21' }`
* `maxDistance`: maximum search distance, in meters

Example:

```javascript
const result = await viewer.setPosition(
	{ latitude: 45.5017, longitude: -73.5673 },
	{
		keepPreviousAngles: true,
		dateFilter: { date: '2024-05-21' },
		maxDistance: 25,
	},
)

console.log(result.uid)
```

#### `viewer.setImage(uid)`

Displays a specific panoramic image directly from its technical `uid`.

This method is especially useful when multiple acquisitions are available at the same location and you want to let the user choose which image to display, for example based on capture date.

#### `viewer.setTilt(wantedTilt)`

Sets the vertical tilt of the digital twin view using the specified value. This function returns the new tilt.

#### `viewer.setPan(wantedPan)`

Sets the horizontal rotation of the digital twin view using the specified value. This function returns the new rotation.

#### `viewer.setFov(wantedFov)`

Sets the field of view (FOV) of the digital twin view using the specified value. This function returns the new FOV value.

#### `viewer.setMarkers(geojsonDisplay)`

Displays markers in the viewer from a GeoJSON object. This method is useful for projecting points of interest from your own application into the panoramic image.

### Choose an Image by Date

When multiple panoramic images exist for the same location, the API allows you to build an image selector in your application.

The workflow is as follows:

1. your application listens to the `position` event
2. the event exposes the current image and the list of available images at that location
3. you render those options in a dropdown
4. when the user selects another image, you call `viewer.setImage(uid)`

Example with Vue 3:

```javascript
import { ref, watch } from 'vue'

const currentImageId = ref(null)
const availableImages = ref([])

window.jakartowns.app.create_jakartowns(
	'#detail-panel__jakartowns__app',
	jakartownsOptions,
	(viewer) => {
		window.jakartowns_instance = viewer

		window.addEventListener('position', (event) => {
			availableImages.value = (event.detail.multipassAtLocation || []).map(
				({ properties: { image_id: imageUid, date } }) => ({
					imageUid,
					date,
				}),
			)

			currentImageId.value =
				event.detail.currentSphereInfo?.properties?.image_id || null
		})

		watch(currentImageId, (newImageId) => {
			if (!newImageId) return
			window.jakartowns_instance.setImage(newImageId)
		})
	},
)
```

If you already know the target date when positioning the viewer, you can also request it directly with `viewer.setPosition()` through the `dateFilter` option.

### Events

#### `position`

This event is triggered when the user changes position in the digital twin. It provides, among other things:

* `uid`: the technical identifier of the displayed image
* `latitude` and `longitude`: the coordinates of the current position
* `currentSphereInfo`: the metadata of the currently displayed image
* `multipassAtLocation`: the list of images available at this location, useful for building a selector by date or image identifier

#### `rotation`

This event is triggered when the user changes the horizontal rotation of the digital twin’s view. It provides the new rotation value.

#### `tilt`

This event is triggered when the user changes the vertical tilt of the digital twin’s view. It provides the new tilt value.

#### `fov`

This event is triggered when the user changes the field of view (FOV) of the digital twin’s view. It provides the new FOV value.


---

# 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.jakarto.com/guide-jakartowns/en/developers/api-javascript/references-de-lapi.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.