> For the complete documentation index, see [llms.txt](https://docs.jakarto.com/guide-jakartowns/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.jakarto.com/guide-jakartowns/fr/developpeurs/api-javascript/references-de-lapi.md).
# Références de l'API
L'API JavaScript de Jakartowns permet d'intégrer le jumeau numérique Jakartowns dans des applications web tierces. Le script JavaScript contient le code informatique de l'API avec toutes ses fonctions et méthodes pour manipuler le jumeau numérique.
L'API facilite ainsi l'interaction avec le jumeau numérique en fournissant des méthodes pour définir la position, la rotation, le tilt, le champ de vision de la vue, ainsi que l'image panoramique affichée.
L'API s'applique sur un conteneur HTML de la page web applicative.
Une fois l'API récupérée, la fonction `create_jakartowns` est disponible pour créer une instance du jumeau numérique Jakartowns dans un conteneur spécifique sur la page web.
window.jakartowns.app.create_jakartowns('#app', options, callback)
Cette fonction est responsable de créer le jumeau numérique Jakartowns dans le conteneur spécifié, avec les options de configuration spécifiées, et exécute la fonction de rappel une fois que le jumeau numérique est prêt à être utilisé. Cela permet aux développeurs d'interagir avec le jumeau numérique et de personnaliser son comportement en fonction de leurs besoins spécifiques.\
\\
Voici une explication détaillée de chaque paramètre de cette fonction :
1. `'#app'`: C'est le sélecteur CSS de l'élément sur la page HTML où vous souhaitez afficher le jumeau numérique. Dans ce cas, l'élément avec l'ID "app" sera utilisé comme conteneur pour le jumeau numérique.
2. `options`: C'est un objet JavaScript contenant les options de configuration pour le jumeau numérique. Ces options permettent de contrôler si l'en-tête et la mini-carte du jumeau numérique sont activés ou désactivés.
3. `callback`: C'est une fonction de rappel (callback) qui est appelée une fois que l'instance du jumeau numérique est créée et prête à être utilisée. Cette fonction de rappel peut être définie comme une fonction anonyme (arrow function) qui prend un paramètre `viewer`. Ce paramètre `viewer` correspond à l'instance du jumeau numérique créée. Vous pouvez utiliser cette instance pour effectuer des actions et des opérations spécifiques sur le jumeau numérique, par exemple, ajouter des écouteurs pour les événements de mise à jour de position, rotation, tilt et fov.
### Fonctions pour interagir avec le jumeau numérique
Les fonctions suivantes sont disponibles sur l'instance `viewer` renvoyée dans le callback de `create_jakartowns`.
#### `viewer.setPosition({ latitude, longitude }, options)`
Définit la position de la vue du jumeau numérique sur la carte en utilisant les coordonnées de latitude et de longitude spécifiées.
Cette fonction renvoie une promesse résolue avec un objet contenant :
* `uid` : l'identifiant technique de l'image sélectionnée
* `distance` : la distance entre la position demandée et l'image panoramique sélectionnée
* `nearest` : l'entité GeoJSON représentant l'image panoramique retenue
* `features` : la liste des panoramas candidats retournés par la recherche
Options disponibles :
* `keepPreviousAngles` : conserve l'orientation actuelle si la valeur est `true` pendant la transition (default: false)
* `observerShift` : permet d'avancer ou reculer dans la trajectoire avec `{ direction: 'forward' | 'backward', steps: number }`
* `dateFilter` : permet de filtrer les images par date, par exemple `{ date: '2024-05-21' }`
* `maxDistance` : distance maximale de recherche, en mètres
Exemple :
```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)`
Affiche directement une image panoramique donnée à partir de son identifiant technique `uid`.
Cette méthode est particulièrement utile lorsque plusieurs acquisitions sont disponibles à une même position et que vous souhaitez laisser l'utilisateur choisir l'image à afficher, par exemple selon sa date de prise de vue.
#### `viewer.setTilt(wantedTilt)`
Définit l'inclinaison verticale de la vue du jumeau numérique en utilisant la valeur spécifiée. Cette fonction renvoie la nouvelle inclinaison.
#### `viewer.setPan(wantedPan)`
Définit la rotation horizontale de la vue du jumeau numérique en utilisant la valeur spécifiée. Cette fonction renvoie la nouvelle rotation.
#### `viewer.setFov(wantedFov)`
Définit le champ de vision (FOV) de la vue du jumeau numérique en utilisant la valeur spécifiée. Cette fonction renvoie la nouvelle valeur de FOV.
#### `viewer.setMarkers(geojsonDisplay)`
Affiche des marqueurs dans le viewer à partir d'un objet GeoJSON. Cette méthode est utile pour projeter dans l'image panoramique des points d'intérêt issus de votre propre application.
### Choisir une image par date
Lorsqu'il existe plusieurs images panoramiques pour une même position, l'API permet de construire un sélecteur d'images côté application.
Le principe est le suivant :
1. votre application écoute l'événement `position`
2. l'événement expose l'image courante et la liste des images disponibles à cet endroit
3. vous affichez ces options dans une liste déroulante
4. lorsque l'utilisateur sélectionne une autre image, vous appelez `viewer.setImage(uid)`
Exemple avec 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)
})
},
)
```
Si vous connaissez déjà la date cible au moment du positionnement, vous pouvez aussi la demander directement avec `viewer.setPosition()` via l'option `dateFilter`.
### Événements
#### `position`
Cet événement est déclenché lorsque l'utilisateur change de position dans le jumeau numérique. Il fournit notamment :
* `uid` : l'identifiant technique de l'image affichée
* `latitude` et `longitude` : les coordonnées de la position courante
* `currentSphereInfo` : les métadonnées de l'image actuellement affichée
* `multipassAtLocation` : la liste des images disponibles à cette position, utile pour construire un sélecteur par date ou par identifiant d'image
#### `rotation`
Cet événement est déclenché lorsque l'utilisateur change la rotation horizontale de la vue du jumeau numérique. Il fournit la nouvelle valeur de rotation.
#### `tilt`
Cet événement est déclenché lorsque l'utilisateur change l'inclinaison verticale de la vue du jumeau numérique. Il fournit la nouvelle valeur d'inclinaison.
#### `fov`
Cet événement est déclenché lorsque l'utilisateur change le champ de vision (FOV) de la vue du jumeau numérique. Il fournit la nouvelle valeur de FOV.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.jakarto.com/guide-jakartowns/fr/developpeurs/api-javascript/references-de-lapi.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.