Skip to content

API

Panoramax.utils.API

Kind: static class of Panoramax.utils
Emits: ready, broken

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)
[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
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
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
Returns: Array.<string> - Keywords of enabled features

api.getUnavailableFeatures() ⇒ Array.<string>

List of unavailable features on API

Kind: instance method of API
Returns: Array.<string> - Keywords of disabled features

api.getSequenceItems(seqId, [next], [data], [limit]) ⇒ Promise

Get sequence GeoJSON representation

Kind: instance method of 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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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

API.isValidHttpUrl(str) ⇒ boolean

Checks URL string validity

Kind: static method of 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
Returns: boolean - True if valid
Throws:

  • Error If not valid
Param Type Description
id string The ID to check