Map | XYZ Maps Documentation

XYZ Map is a highly customizable WebGL based vector map display that's optimized for map editing, larger raw datasets and frequently changing data.

Hierarchy

Index

Constructors

constructor

Constructors

constructor

new Map(mapEl: HTMLElement, options: MapOptions): Map

example

import {Map} from '@here/xyz-maps-display';

//create map display
const display = new Map( mapDiv, {
    zoomLevel : 19,
    center: {
        longitude: 8.53422,
        latitude: 50.16212
    },
    // add layers to display
    layers: layers
});

Parameters

mapEl: HTMLElement

HTMLElement used to create the map display
options: MapOptions

options to configure for the map

Returns Map

Methods

addEventListener

addEventListener(type: string, listener: (e: MapEvent) => void): void

Adds an event listener to the map. supported events: 'mapviewchangestart', 'mapviewchange', 'mapviewchangeend', 'resize', 'tap', 'dbltap', 'pointerup', 'pointerenter', 'pointerleave', 'pointerdown', 'pointermove', 'pressmove'

Parameters
- type: string
  
  A string representing the event type to listen for.
- listener: (e: MapEvent) => void
  
  the listener function that will be called when an event of the specific type occurs
  - - (e: MapEvent): void
    - Parameters
      - e: MapEvent
      Returns void
Returns void

addLayer

addLayer(layer: TileLayer | CustomLayer, index?: number): void

Adds a layer to the map.

If an index is provided, the layer will be inserted at the specified position within the layer hierarchy, which allows placing the layer between existing layers. If the index is not specified, the layer will be added on top of all existing layers (i.e., as the last layer in the hierarchy).

The index is zero-based, meaning an index of 0 will insert the layer at the bottom, and an index equal to the current number of layers will place it on top. If the specified index exceeds the current number of layers, the layer will be added on top.

Parameters
- layer: TileLayer | CustomLayer
  
  The layer to be added to the map. This can be a TileLayer or a CustomLayer.
- Optional index: number
  
  (Optional) The zero-based index in the layer hierarchy where the layer should be inserted. If omitted, the layer will be added as the topmost layer.
Returns void

addObserver

addObserver(name: string, observer: (name: string, newValue: any, prevValue: any) => void): boolean

Add an observer to the map. Supported observers are: "zoomlevel", "center", "rotation" and "pitch".

Parameters
- name: string
  
  the name of the value to observe
- observer: (name: string, newValue: any, prevValue: any) => void
  
  the observer that will be executed on value changes.
  - - (name: string, newValue: any, prevValue: any): void
    - Parameters
      - name: string
      - newValue: any
      - prevValue: any
      Returns void
Returns boolean

boolean that's indicating if observer was added.

destroy

destroy(): void

Destroy the the map.

Returns void

flyTo

flyTo(center: GeoPoint, options?: { duration?: number }): any
flyTo(center: GeoPoint, zoomTo: number, options?: { duration?: number }): any

Set the map center using a bow animation combining pan and zoom operations.

Parameters
- center: GeoPoint
  
  the geographical coordinate to center the map.
- Optional options: { duration?: number }
  
  options to configure the bow animation
  - Optional duration?: number
    
    the duration of the bow animation in milliseconds
Returns any
Set the map center and zoomlevel using a bow animation combining pan and zoom operations.

Parameters
- center: GeoPoint
  
  the geographical coordinate to center the map.
- zoomTo: number
  
  the zoomlevel the map should be zoomed to.
- Optional options: { duration?: number }
  
  options to configure the bow animation
  - Optional duration?: number
    
    the duration of the bow animation in milliseconds
Returns any

geoToPixel

geoToPixel(longitude: number, latitude: number, altitude?: number): PixelPoint
geoToPixel(coordinate: GeoPoint): PixelPoint

Convert a geographical coordinate to a pixel coordinate relative to the current viewport of the map.

Parameters
- longitude: number
  
  the longitude in degrees
- latitude: number
  
  the latitude in degrees
- Optional altitude: number
  
  the altitude in meters
Returns PixelPoint

the pixel coordinate relative to the current viewport.
Convert a geographical coordinate to a pixel coordinate relative to the current viewport of the map.

Parameters
- coordinate: GeoPoint
  
  the geographical coordinate
Returns PixelPoint

the pixel coordinate relative to the current viewport.

getBehavior

getBehavior(): { drag: boolean; pitch: boolean; rotate: boolean; zoom: boolean }

Get current active map behavior options.

Returns { drag: boolean; pitch: boolean; rotate: boolean; zoom: boolean }
- drag: boolean
  
  indicates if map dragging is enabled or disabled.
- pitch: boolean
  
  indicates if map pitching is enabled or disabled.
- rotate: boolean
  
  indicates if map rotation is enabled or disabled.
- zoom: boolean
  
  indicates if map zooming is enabled or disabled.

getCamera

getCamera(): { position: { altitude: number; latitude: number; longitude: number } }

Get the camera of the current viewport.

experimental

Returns { position: { altitude: number; latitude: number; longitude: number } }
- position: { altitude: number; latitude: number; longitude: number }
  
  The camera's center position in geographical coordinates (world-space).
  - altitude: number
  - latitude: number
  - longitude: number

getCenter

getCenter(): GeoPoint

Get the current geographical center of the map.

Returns GeoPoint

the map's geographical center point.

getContainer

getContainer(): HTMLElement

Get the HTMLElement used by the map.

Returns HTMLElement

getFeatureAt

getFeatureAt(position: PixelPoint | PixelRect, options?: { height?: number; layers?: TileLayer | TileLayer[]; width?: number }): { feature: Feature; layer: TileLayer } | undefined

Get most top rendered feature within the given area of map

Parameters
- position: PixelPoint | PixelRect
  
  Point or Rect in pixel to define search area. If a Point is used, width and height must be passed in options parameter.
- Optional options: { height?: number; layers?: TileLayer | TileLayer[]; width?: number }
  
  Describing the options param
  - Optional height?: number
    
    height in pixel of rectangle if point geometry is used.
  - Optional layers?: TileLayer | TileLayer[]
    
    defines the layer(s) to search in.
  - Optional width?: number
    
    width in pixel of rectangle if point geometry is used.
Returns { feature: Feature; layer: TileLayer } | undefined

The result providing found feature and layer. undefined is returned if nothing is found.

getFeaturesAt

getFeaturesAt(position: PixelPoint | PixelRect, options?: { height?: number; layers?: TileLayer | TileLayer[]; width?: number }): { features: Feature[]; layer: TileLayer }[]

Get rendered features within the given area of map

Parameters
- position: PixelPoint | PixelRect
  
  Point or Rect in pixel to define search area. If a Point is used, width and height must be passed in options parameter.
- Optional options: { height?: number; layers?: TileLayer | TileLayer[]; width?: number }
  
  Describing the options param
  - Optional height?: number
    
    height in pixel of rectangle if point geometry is used.
  - Optional layers?: TileLayer | TileLayer[]
    
    defines the layer(s) to search in.
  - Optional width?: number
    
    width in pixel of rectangle if point geometry is used.
Returns { features: Feature[]; layer: TileLayer }[]

zIndex ordered results array

getHeight

getHeight(): number

Get the current height in pixels of map.

Returns number

getLayers

getLayers(): TileLayer[]
getLayers(index: number): TileLayer

Get the current added layer(s) of the map.

Returns TileLayer[]

the layer(s) that are added to the map
Get a specific Layer of the map.

Parameters
- index: number
  
  get a specific layer at index in the layer hierarchy
Returns TileLayer

the layer that is added to the map

getViewBounds

getViewBounds(): GeoRect

Gets the current view bounds of the view port.

Returns GeoRect

getWidth

getWidth(): number

Get the current width in pixels of map.

Returns number

getZoomlevel

getZoomlevel(): number

Get the current zoom level

Returns number

the current zoom level of the map

lockViewport

lockViewport(): { maxLevel: number; minLevel: number; pan: boolean }
lockViewport(options: { maxLevel?: number; minLevel?: number; pan?: boolean }): { maxLevel: number; minLevel: number; pan: boolean }

get the current applied lock status of the map.

Returns { maxLevel: number; minLevel: number; pan: boolean }

the current applied lock options.
- maxLevel: number
- minLevel: number
- pan: boolean
set lock the viewport of the map. by indicating if panning, minLevel and maxLevel should be locked.

Parameters
- options: { maxLevel?: number; minLevel?: number; pan?: boolean }
  
  the lock options.
  - Optional maxLevel?: number
    
    the maximum allowed zoom level that can be zoomed to.
  - Optional minLevel?: number
    
    the minimum allowed zoom level that can be zoomed to.
  - Optional pan?: boolean
    
    true to enable panning, false to disable panning.
Returns { maxLevel: number; minLevel: number; pan: boolean }

the current applied lock options.
- maxLevel: number
- minLevel: number
- pan: boolean

pan

pan(dx: number, dy: number): void

Shift the geographical center of the map in pixels.

Parameters
- dx: number
  
  distance in pixels to pan the map on x axis
- dy: number
  
  distance in pixels to pan the map on y axis
Returns void

pitch

pitch(pitch?: number): number

Set or get map pitch (tilt) in degrees

Parameters
- Optional pitch: number
  
  pitch in degrees
Returns number

pixelToGeo

pixelToGeo(x: number, y: number): GeoPoint
pixelToGeo(position: PixelPoint): GeoPoint

Converts from screen pixel to geo coordinate

Parameters
- x: number
  
  the x position on screen in pixel
- y: number
  
  the y position on screen in pixel
Returns GeoPoint

the geographical coordinate
Converts from screen pixel to geo coordinate

Parameters
- position: PixelPoint
  
  the pixel coordinate on screen
Returns GeoPoint

the geographical coordinate

refresh

refresh(layers?: TileLayer | Layer | (TileLayer | Layer)[]): void

Refresh the map view. Manually trigger re-rendering of specific layer(s) of the map.

Parameters
- Optional layers: TileLayer | Layer | (TileLayer | Layer)[]
  
  the layer(s) that should be refreshed/re-rendered.
Returns void

removeEventListener

removeEventListener(type: string, listener: (e: MapEvent) => void): void

Removes an event listener to the map.

Parameters
- type: string
  
  A string representing the event type to listen for.
- listener: (e: MapEvent) => void
  
  The EventListener function of the event handler to remove from the editor.
  - - (e: MapEvent): void
    - Parameters
      - e: MapEvent
      Returns void
Returns void

removeLayer

removeLayer(layer: TileLayer | CustomLayer): void

Remove a layer from the map.

Parameters
- layer: TileLayer | CustomLayer
  
  the layer to remove
Returns void

removeObserver

removeObserver(name: string, observer: (name: string, newValue: any, prevValue: any) => void): boolean

Removes an observer from the map.

Parameters
- name: string
  
  the name of the value to observe
- observer: (name: string, newValue: any, prevValue: any) => void
  
  the observer that should be removed.
  - - (name: string, newValue: any, prevValue: any): void
    - Parameters
      - name: string
      - newValue: any
      - prevValue: any
      Returns void
Returns boolean

boolean that's indicating if observer was removed.

resize

resize(width?: number, height?: number): void

Resize the map view. If no width/height is passed the map will resize automatically to the maximum possible size defined by the HTMLElement.

Parameters
- Optional width: number
  
  new width in pixels
- Optional height: number
  
  new height in pixels
Returns void

rotate

rotate(rotation?: number): number

Set or get map rotation along z-axis

Parameters
- Optional rotation: number
  
  set absolute map rotation in degrees
Returns number

current applied rotation in degrees

setBackgroundColor

setBackgroundColor(color: Color): void

Set the background color of the map

Parameters
- color: Color
  
  the background color to set
Returns void

setBehavior

setBehavior(options: { drag?: boolean; pitch?: boolean; rotate?: boolean; zoom?: boolean }): void
setBehavior(behavior: string, active: boolean): any

Set the map behavior on user interaction.
example
```
// to deactivate map zoom on mouse scroll:
setBehavior({zoom: false, drag: true});
```
Parameters
- options: { drag?: boolean; pitch?: boolean; rotate?: boolean; zoom?: boolean }
  
  Behavior options
  - Optional drag?: boolean
    
    true to enable map dragging, false to disable.
  - Optional pitch?: boolean
    
    true to enable map pitching, false to disable.
  - Optional rotate?: boolean
    
    true to enable map rotation, false to disable.
  - Optional zoom?: boolean
    
    true to enable map zooming, false to disable.
Returns void
Enable/Disable a specific map behavior on user interaction. Possible behavior are: "zoom", "drag", "pitch" and "rotate
example
```
// to deactivate map zoom on mouse scroll:
setBehavior('zoom',true);
```
Parameters
- behavior: string
  
  the behavior that should be disabled or enabled.
- active: boolean
  
  true to enable, false to disable
Returns any

setCenter

setCenter(center: GeoPoint): any
setCenter(longitude: number | GeoPoint, latitude: number): any

Set new geographical center for the map.
example
```
display.setCenter({longitude: 8.53422, latitude: 50.16212});
```
Parameters
- center: GeoPoint
  
  the geographical coordinate to center the map
Returns any
Set new geographical center for the map.
example
```
display.setCenter(8.53422, 50.16212);
```
Parameters
- longitude: number | GeoPoint
- latitude: number
  
  latitude to center the map
Returns any

setViewBounds

setViewBounds(bounds: GeoRect | [number, number, number, number] | GeoJSONFeature | GeoJSONFeature[] | GeoJSONFeatureCollection, animate?: boolean): any
setViewBounds(bounds: GeoRect | [number, number, number, number] | GeoJSONFeature | GeoJSONFeature[] | GeoJSONFeatureCollection, animationOptions?: { duration?: number }): any

Set view bounds for the map to display.

Parameters
- bounds: GeoRect | [number, number, number, number] | GeoJSONFeature | GeoJSONFeature[] | GeoJSONFeatureCollection
  
  GeoRect, GeoJson Feature or an GeoJson bbox [minLon, minLat, maxLon, maxLat] defining the view bounds.
- Optional animate: boolean
  
  animate using a bow animation @see Map.flyTo. true to enable, false to disable.
Returns any
Set view bounds for the map to display.

Parameters
- bounds: GeoRect | [number, number, number, number] | GeoJSONFeature | GeoJSONFeature[] | GeoJSONFeatureCollection
  
  GeoRect, GeoJson Feature or an GeoJson bbox [minLon, minLat, maxLon, maxLat] defining the view bounds.
- Optional animationOptions: { duration?: number }
  
  options to configure the bow animation @see Map.flyTo.
  - Optional duration?: number
    
    the duration of the bow animation in milliseconds
Returns any

setZoomlevel

setZoomlevel(zoomTo: number, fixedX?: number, fixedY?: number, animate?: number): void

Set zoomlevel with an optional anchor point.

Parameters
- zoomTo: number
  
  new zoomlevel
- Optional fixedX: number
  
  x coordinate of fixed anchor point on screen in pixels
- Optional fixedY: number
  
  y coordinate of fixed anchor point on screen in pixels
- Optional animate: number
  
  zoom transition animation time in milliseconds [default: 0]
Returns void

snapshot

snapshot(callback: (screenshot: HTMLCanvasElement) => void, dx?: number, dy?: number, width?: number, height?: number): void

Take a snapshot of the current map's viewport.

Parameters
- callback: (screenshot: HTMLCanvasElement) => void
  
  Callback function that will be called when the requested snapshot has been captured.
  - - (screenshot: HTMLCanvasElement): void
    - Parameters
      - screenshot: HTMLCanvasElement
      Returns void
- Optional dx: number
  
  x coordinate of the left edge of the capturing rectangle in pixel
- Optional dy: number
  
  y coordinate of the top edge of the capturing rectangle in pixel
- Optional width: number
  
  width of the capturing rectangle in pixel
- Optional height: number
  
  height of the capturing rectangle in pixel
Returns void

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Parameters

mapEl: HTMLElement

options: MapOptions

Returns Map

Methods

addEventListener

Parameters

type: string

listener: (e: MapEvent) => void

Parameters

e: MapEvent

Returns void

Returns void

addLayer

Parameters

layer: TileLayer | CustomLayer

Optional index: number

Returns void

addObserver

Parameters

name: string

observer: (name: string, newValue: any, prevValue: any) => void

Parameters

name: string

newValue: any

prevValue: any

Returns void

Returns boolean

destroy

Returns void

flyTo

Parameters

center: GeoPoint

Optional options: { duration?: number }

Optional duration?: number

Returns any

Parameters

center: GeoPoint

zoomTo: number

Optional options: { duration?: number }

Optional duration?: number

Returns any

geoToPixel

Parameters

longitude: number

latitude: number

Optional altitude: number

Returns PixelPoint

Parameters

coordinate: GeoPoint

Returns PixelPoint

getBehavior

Returns { drag: boolean; pitch: boolean; rotate: boolean; zoom: boolean }

drag: boolean

pitch: boolean

rotate: boolean

zoom: boolean

getCamera

Returns { position: { altitude: number; latitude: number; longitude: number } }

position: { altitude: number; latitude: number; longitude: number }

altitude: number

latitude: number

longitude: number

getCenter

Returns GeoPoint

getContainer

Returns HTMLElement

getFeatureAt

Parameters

position: PixelPoint | PixelRect

Optional options: { height?: number; layers?: TileLayer | TileLayer[]; width?: number }

Optional height?: number

Optional layers?: TileLayer | TileLayer[]

Optional width?: number