## Panoramax.utils.API **Kind**: static class of Panoramax.utils **Emits**: [ready](#Panoramax.utils.API+event_ready), [broken](#Panoramax.utils.API+event_broken) * [.API](#Panoramax.utils.API) * [new API(endpoint, [options])](#new_Panoramax.utils.API_new) * _instance_ * [.onceReady()](#Panoramax.utils.API+onceReady) ⇒ Promise * [.isReady()](#Panoramax.utils.API+isReady) ⇒ boolean * [.getAvailableFeatures()](#Panoramax.utils.API+getAvailableFeatures) ⇒ Array.<string> * [.getUnavailableFeatures()](#Panoramax.utils.API+getUnavailableFeatures) ⇒ Array.<string> * [.getSequenceItems(seqId, [next], [data], [limit])](#Panoramax.utils.API+getSequenceItems) ⇒ Promise * [.getPicturesAroundCoordinatesUrl(lat, lon, [factor], [limit], [seqId])](#Panoramax.utils.API+getPicturesAroundCoordinatesUrl) ⇒ string * [.getPicturesAroundCoordinates(lat, lon, [factor], [limit], [seqId])](#Panoramax.utils.API+getPicturesAroundCoordinates) ⇒ Promise * [.getPictureMetadataUrl(picId, [seqId])](#Panoramax.utils.API+getPictureMetadataUrl) ⇒ string * [.getMapStyle()](#Panoramax.utils.API+getMapStyle) ⇒ Promise \| object * [.getUserMapStyle(userId, [skipReadyCheck])](#Panoramax.utils.API+getUserMapStyle) ⇒ Promise * [.getPictureThumbnailURLForSequence(seqId, [seq])](#Panoramax.utils.API+getPictureThumbnailURLForSequence) ⇒ Promise * [.getPictureThumbnailURL(picId, [seqId])](#Panoramax.utils.API+getPictureThumbnailURL) ⇒ Promise * [.getRSSURL([bbox])](#Panoramax.utils.API+getRSSURL) ⇒ string \| null * [.getSequenceMetadataUrl(seqId)](#Panoramax.utils.API+getSequenceMetadataUrl) ⇒ string * [.getSequenceMetadata(seqId)](#Panoramax.utils.API+getSequenceMetadata) ⇒ Promise * [.getDataBbox()](#Panoramax.utils.API+getDataBbox) ⇒ LngLatBoundsLike * [.searchUsers(query)](#Panoramax.utils.API+searchUsers) ⇒ Promise * [.getUserName(userId)](#Panoramax.utils.API+getUserName) ⇒ Promise * [.sendReport(data)](#Panoramax.utils.API+sendReport) ⇒ Promise * [.sendPictureSemantics(picMeta, semanticsDiff)](#Panoramax.utils.API+sendPictureSemantics) ⇒ Promise * [.createPictureAnnotation(picMeta, shape, semanticsDiff)](#Panoramax.utils.API+createPictureAnnotation) ⇒ Promise * [.editPictureAnnotation(annotationId, semanticsDiff)](#Panoramax.utils.API+editPictureAnnotation) ⇒ Promise * [.deletePictureAnnotation(annotationId)](#Panoramax.utils.API+deletePictureAnnotation) ⇒ Promise * [.getAuthURL()](#Panoramax.utils.API+getAuthURL) ⇒ Promise * ["broken"](#Panoramax.utils.API+event_broken) * ["ready"](#Panoramax.utils.API+event_ready) * _static_ * [.isValidHttpUrl(str)](#Panoramax.utils.API.isValidHttpUrl) ⇒ boolean * [.isIdValid(id)](#Panoramax.utils.API.isIdValid) ⇒ boolean ### new API(endpoint, [options]) API contains various utility functions to communicate with Panoramax/STAC API | Param | Type | Default | Description | | --- | --- | --- | --- | | endpoint | string | | The endpoint. It corresponds to the STAC landing page, with all links describing the API capabilities. | | [options] | object | | Options | | [options.style] | string \| object | | General map style | | [options.tiles] | string | | API route serving pictures & sequences vector tiles | | [options.skipReadLanding] | boolean | false | True to not call API landing page automatically | | [options.fetch] | object | | Set custom options for fetch calls made against API ([same syntax as fetch options parameter](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters)) | | [options.users] | Array.<string> | | List of initial user IDs to load map styles for | ### api.onceReady() ⇒ Promise Resolves when the API is ready to be used. **Kind**: instance method of [API](#Panoramax.utils.API) **Fulfil**: string "API is ready" when initialization is complete. **Reject**: string Error message ### api.isReady() ⇒ boolean Checks if the API is ready to be used. **Kind**: instance method of [API](#Panoramax.utils.API) **Returns**: boolean - True if the API is ready, false otherwise. ### api.getAvailableFeatures() ⇒ Array.<string> List of available features offered by API **Kind**: instance method of [API](#Panoramax.utils.API) **Returns**: Array.<string> - Keywords of enabled features ### api.getUnavailableFeatures() ⇒ Array.<string> List of unavailable features on API **Kind**: instance method of [API](#Panoramax.utils.API) **Returns**: Array.<string> - Keywords of disabled features ### api.getSequenceItems(seqId, [next], [data], [limit]) ⇒ Promise Get sequence GeoJSON representation **Kind**: instance method of [API](#Panoramax.utils.API) **Fulfil**: object Sequence GeoJSON **Reject**: Error If API is not ready or for any network issue | Param | Type | Default | Description | | --- | --- | --- | --- | | seqId | string | | The sequence ID | | [next] | string | null | The next link URL (only for internals) | | [data] | object | | The previous dataset (only for internals) | | [limit] | number | | How many items to retrieve (defaults to unset). If set, pages are not looked through. | ### api.getPicturesAroundCoordinatesUrl(lat, lon, [factor], [limit], [seqId]) ⇒ string Get full URL for listing pictures around a specific location **Kind**: instance method of [API](#Panoramax.utils.API) **Returns**: string - The corresponding URL | Param | Type | Default | Description | | --- | --- | --- | --- | | lat | number | | Latitude | | lon | number | | Longitude | | [factor] | number | 0.0005 | The radius to search around (in degrees) | | [limit] | number | | Max amount of pictures to retrieve | | [seqId] | string | | The sequence ID to filter on (by default, no filter) | ### api.getPicturesAroundCoordinates(lat, lon, [factor], [limit], [seqId]) ⇒ Promise Get list of pictures around a specific location **Kind**: instance method of [API](#Panoramax.utils.API) **Fulfil**: object The GeoJSON feature collection | Param | Type | Description | | --- | --- | --- | | lat | number | Latitude | | lon | number | Longitude | | [factor] | number | The radius to search around (in degrees) | | [limit] | number | Max amount of pictures to retrieve | | [seqId] | string | The sequence ID to filter on (by default, no filter) | ### api.getPictureMetadataUrl(picId, [seqId]) ⇒ string Get full URL for retrieving a specific picture metadata **Kind**: instance method of [API](#Panoramax.utils.API) **Returns**: string - The corresponding URL **Throws**: - Error If API is not ready | Param | Type | Description | | --- | --- | --- | | picId | string | The picture unique identifier | | [seqId] | string | The sequence ID | ### api.getMapStyle() ⇒ Promise \| object Get JSON style for general vector tiles **Kind**: instance method of [API](#Panoramax.utils.API) **Returns**: Promise \| object - Promise if first load, MapLibre JSON style otherwise **Fulfil**: object The MapLibre JSON style **Reject**: Error If API is not ready, or no style defined. ### api.getUserMapStyle(userId, [skipReadyCheck]) ⇒ Promise Get JSON style for specific-user vector tiles **Kind**: instance method of [API](#Panoramax.utils.API) **Fulfil**: object The MapLibre JSON style **Reject**: Error If API is not ready, or no style defined. | Param | Type | Default | Description | | --- | --- | --- | --- | | userId | string | | The user UUID | | [skipReadyCheck] | boolean | false | Skip check for API readyness | ### api.getPictureThumbnailURLForSequence(seqId, [seq]) ⇒ Promise Get a picture thumbnail URL for a given sequence **Kind**: instance method of [API](#Panoramax.utils.API) **Throws**: - Error If API is not ready **Fulfil**: string\|null Promise resolving on the picture thumbnail URL, or null if not found | Param | Type | Description | | --- | --- | --- | | seqId | string | The sequence ID | | [seq] | object | The sequence metadata (with links) if already loaded | ### api.getPictureThumbnailURL(picId, [seqId]) ⇒ Promise Get thumbnail URL for a specific picture **Kind**: instance method of [API](#Panoramax.utils.API) **Throws**: - Error If API is not ready **Fulfil**: string\|null The corresponding URL on resolve, or null if no thumbnail could be found | Param | Type | Description | | --- | --- | --- | | picId | string | The picture unique identifier | | [seqId] | string | The sequence ID | ### api.getRSSURL([bbox]) ⇒ string \| null Get the RSS feed URL with map parameters (if map is enabled) **Kind**: instance method of [API](#Panoramax.utils.API) **Returns**: string \| null - The URL, or null if no RSS feed is available **Throws**: - Error If API is not ready | Param | Type | Description | | --- | --- | --- | | [bbox] | LngLatBounds | The map current bounding box, or null if not available | ### api.getSequenceMetadataUrl(seqId) ⇒ string Get full URL for retrieving a specific sequence metadata **Kind**: instance method of [API](#Panoramax.utils.API) **Returns**: string - The corresponding URL **Throws**: - Error If API is not ready | Param | Type | Description | | --- | --- | --- | | seqId | string | The sequence ID | ### api.getSequenceMetadata(seqId) ⇒ Promise Retrieve metadata for a specific sequence **Kind**: instance method of [API](#Panoramax.utils.API) **Throws**: - Error If API is not ready **Fulfil**: object\|null Sequence metadata | Param | Type | Description | | --- | --- | --- | | seqId | string | The sequence ID | ### api.getDataBbox() ⇒ LngLatBoundsLike Get available data bounding box **Kind**: instance method of [API](#Panoramax.utils.API) **Returns**: LngLatBoundsLike - The bounding box or null if not available **Throws**: - Error If API is not ready ### api.searchUsers(query) ⇒ Promise Look for user ID based on user name query **Kind**: instance method of [API](#Panoramax.utils.API) **Throws**: - Error If API is not ready or user search not available **Fulfil**: object\|null List of potential users | Param | Type | Description | | --- | --- | --- | | query | string | The user name to look for | ### api.getUserName(userId) ⇒ Promise Get user name based on its ID **Kind**: instance method of [API](#Panoramax.utils.API) **Throws**: - Error If API is not ready **Fulfil**: string\|null The user name (or null if not found) | Param | Type | Description | | --- | --- | --- | | userId | string | The user UUID | ### api.sendReport(data) ⇒ Promise Send a report to API **Kind**: instance method of [API](#Panoramax.utils.API) **Fulfil**: object The JSON API response | Param | Type | Description | | --- | --- | --- | | data | object | The input form data | ### api.sendPictureSemantics(picMeta, semanticsDiff) ⇒ Promise Send picture semantics change to origin API. **Kind**: instance method of [API](#Panoramax.utils.API) **Fulfil**: object The JSON API response | Param | Type | Description | | --- | --- | --- | | picMeta | object | The picture metadata | | semanticsDiff | object | The difference in semantics compared to original data | ### api.createPictureAnnotation(picMeta, shape, semanticsDiff) ⇒ Promise Create new annotation for a given picture on its origin API. **Kind**: instance method of [API](#Panoramax.utils.API) **Fulfil**: object The JSON API response | Param | Type | Description | | --- | --- | --- | | picMeta | object | The picture metadata | | shape | object | The annotation shape | | semanticsDiff | object | The difference in semantics compared to original data | ### api.editPictureAnnotation(annotationId, semanticsDiff) ⇒ Promise Edit semantics of an existing annotation on its origin API. **Kind**: instance method of [API](#Panoramax.utils.API) **Fulfil**: object The JSON API response | Param | Type | Description | | --- | --- | --- | | annotationId | string | The annotation UUID | | semanticsDiff | object | The difference in semantics compared to original data | ### api.deletePictureAnnotation(annotationId) ⇒ Promise Delete a single annotation on its origin API. **Kind**: instance method of [API](#Panoramax.utils.API) **Fulfil**: object The JSON API response | Param | Type | Description | | --- | --- | --- | | annotationId | string | The annotation UUID | ### api.getAuthURL() ⇒ Promise Get the URL for user to log-in. **Kind**: instance method of [API](#Panoramax.utils.API) **Fulfil**: string\|boolean The log-in URL, or false if no login is available ### "broken" Event when API is broken. This happens on any API loading or map styling issue. **Kind**: event emitted by [API](#Panoramax.utils.API) **Properties** | Name | Type | Description | | --- | --- | --- | | detail.error | Error | The original error | ### "ready" Event when API is ready to use. This happens after initial API read and map styles load. **Kind**: event emitted by [API](#Panoramax.utils.API) ### API.isValidHttpUrl(str) ⇒ boolean Checks URL string validity **Kind**: static method of [API](#Panoramax.utils.API) **Returns**: boolean - True if valid | Param | Type | Description | | --- | --- | --- | | str | string | The URL to check | ### API.isIdValid(id) ⇒ boolean Checks picture or sequence ID validity **Kind**: static method of [API](#Panoramax.utils.API) **Returns**: boolean - True if valid **Throws**: - Error If not valid | Param | Type | Description | | --- | --- | --- | | id | string | The ID to check |