Skip to content
/ heremap Public

A framework to simplify the use of HERE Maps, which a bunch of higher level functions. In addition, it brings geocoding and routing functions to Node.js

Notifications You must be signed in to change notification settings

devbab/heremap

Repository files navigation

HEREMAP

A framework to simplify the use of HERE Maps, which a bunch of higher level functions. In addition, it brings geocoding and routing functions to Node.js

See examples in the demo directory, starting with demo/demo-basic.html.

Get your credentials at http://developer.here.com

Installation

1/ For use in Node.js, install the package:

npm install --save-dep heremap

To use in a js file

const hm = require("heremap");

hm.config({
	app_id: YOUR APP_ID,
	app_code: YOUR APP_CODE,
});

let res = await hm.geocode("avenue des champs elysees, paris);
console.log(res.coord);

2/ For use in browser, add these lines in your html file

<link rel="stylesheet" type="text/css" href="http://www.unpkg.com/[email protected]/css/heremap.css" />

<script src="http://www.unpkg.com/[email protected]/dist/libhere.min.js" type="text/javascript" charset="utf-8"></script>
<script src="http://www.unpkg.com/[email protected]/dist/heremap.min.js" type="text/javascript" charset="utf-8"></script>

<div id="map"></div>

Then in your JS script:

const hm = window.heremap;

hm.config({
	app_id: YOUR APP_ID,
	app_code: YOUR APP_CODE,
});

hm.map("map", {
	zoom:5,
	center: [48.8,2.3],
	click: function(coord,button,key) {console.log("clicked on",coord,"with button",button);}
});

Demo

See under directory demo:

Functions

hm:bubbleUnique(coord, txt)

Display a unique bubble. Associated CSS style is .H_ib_body

hm:bubbleUniqueHide()

hide a unique bubble

hm:buildIcon(opt)H.map.Icon

create an icon, to be used for a marker

hm:circle(opt)

draw a circle

hm:cluster(coords, opt, cb)H.map.layer.ObjectLayer

Creates a cluster of points

hm:clusterHide()

Hide cluster layer

hm:clusterShow()

Show Cluster layer

hm:config(opt)

To configure app_id, app_code and optionally use CIT and http

hm:coord2Point([lat,lng])array

Convert [lat,lng] to {lat,lng}

hm:coordA2O(arr)array

Convert an array [lat,lng] to {lat,lng}

hm:coordO2A(obj)array

Convert an object {lat,lng} to [lat,lng]

hm:coords2XY(coords)array

Convert array of [lat,lng] to array of {x,y}

hm:detour(start, stop, waypoints)Promise

Compute the detour for each waypoint provided, compared to normal route from A to B

hm:geocode(address)Promise

geocode an address

hm:getAvailableMapStyle()promise

list of all available map styles normal.day, night....

hm:getCenter()coord

return coordinate of the center of the map

hm:getViewBB()Object

return bounding box of visible part of map

hm:getZoom()number

return zoom value

hm:htmlBounding()object

provide bounding box of element hosting map, relatve to window

hm:isoline(opt)Promise

compute an isoline. See more info on optional parameters

hm:layerCreate(name, visible)

create a layer

hm:layerDelete(name)

delete a layer

hm:layerEmpty(layer)

Empty a layer, or create it if not existing

hm:layerFind(name)

find layer by its name or return null

hm:layerSetVisibility(name, visible)

create a layer

hm:locateMe(callback, opt)

watch position on HTML5 position. This requires HTTPS. Creates layer "_gps"

hm:map(htmlItem, opt)

create a map area within the specified item

hm:marker(opt)H.map.Marker

add a marker in a layer svg files can be created with https://editor.method.ac/

hm:matrix(source, dest, opt)Promise

compute a matrix. See more info on optional parameters

Matrix size is limited to 1x100, 100x1 or 15xN

hm:placeAutoSuggest(opt)Promise

Place AutoSuggest @ async

hm:point2Coord({lat,lng})array

Convert {lat,lng} to [lat,lng]

hm:polygon(opt)

Draw a polygon

hm:polyline(opt)

Draw a polyline.

hm:reverseGeocode(coord)Promise

reverse geocode a coordinate

hm:route(source, dest, opt)Promise

compute a route with optional waypooints. See more info on optional parameters

hm:screenshot(opt, opt)data

perform a screenshot of the map and returns a promise with the data

hm:setCenter(coord)

set center of the map

hm:setScheme(scheme)

define the scheme. List of scheme can be obtained from hm.getAvailableMapStyle()

hm:setViewBB(opt)

sets bouding box to be displayed

hm:setZoom(zoom)

set zoom level

hm:simplify(coords, tolerance)array

Simplify a polyline by using the Ramer-Douglas-Peucker algorithm

hm:touch(onoff, options)

activate touch, allowing hand drawing, with embedded simplification of the line

hm:xy2Coords(coords)array

Convert array of {x,y} to array of [lat,lng]

marker:getCoord()coord

get coordinates of a marker

hm:bubbleUnique(coord, txt)

Display a unique bubble. Associated CSS style is .H_ib_body

Kind: global function
Params

  • coord Array - of the bubble
  • txt String - html text to display

hm:bubbleUniqueHide()

hide a unique bubble

Kind: global function

hm:buildIcon(opt) ⇒ H.map.Icon

create an icon, to be used for a marker

Kind: global function
Returns: H.map.Icon - the created icon
Params

  • opt object - options to specify the icon
    • [.img] string - use a png/jpg image. Specify the url
    • [.svg] string - url a svg. This can be an inline svg, a url, or a svg from heremap
    • [.opt] object - style object
      • [.size] number | string - size of icon, as 24 or 24x32
      • [.ratio] number - for svg files, ratio of size. 0.5 = half
      • [.anchor] number | string - anchor of icon, as 24 or "24x32" or "center". By default, bottom-center
      • [.tag] string - for svg, any tag like {tag} within the svg file will be replaced by its associated value

Example

hm.buildIcon({
   img: "http://whatever.com/image.png",
   opt: {size:24}
});

hm.buildIcon({
   svg: "http://whatever.com/image.svg",
   opt: {
      ratio:0.5,
      anchor:24x32
   }
});
 
hm.buildIcon({
   svg: "@svg/cluster.svg",
   opt: {
      size:24,
      color:"red"
   }
});

const svg = `<svg width="16" height="16" xmlns="http://www.w3.org/2000/svg"> <ellipse stroke="null" ry="8" rx="7.618896" id="svg_1" cy="8" cx="7.837427" fill="{color}" fill-opacity="0.9"/></svg>`;
hm.buildIcon({
   svg: svg,
   opt: {
      size:24,
      color:"red"
   } 
});

hm:circle(opt)

draw a circle

Kind: global function
Params

  • opt * - option for circle
    • [.layer] String - optional layer to use
    • [.coord] array - center of the circle, as [48.8,2.3]
    • [.radius] number - radius in meter
    • [.style] object - optional graphic style
      • [.strokeColor] string - color of perimeter
      • [.lineWidth] number - line width
      • [.fillColor] string - fill color

hm:cluster(coords, opt, cb) ⇒ H.map.layer.ObjectLayer

Creates a cluster of points

Kind: global function
Returns: H.map.layer.ObjectLayer - layer created
Params

  • coords Array - array of [lat,lng,payload]
  • opt object - options for cluster
    • [.minZoom] number - min zoom for cluster to be visible
    • [.maxZoom] number - max zoom for cluster to be visible
    • [.noise] object - graphic to represent stand-alone point. {icon,size}
      • [.icon] string - png/jpg/svg file. @ as first character indicates a file from this package. Anchor will be bottom-center
      • [.size] number - optional size of icon
    • [.cluster] object - { weight:{icon,size}, weight:{icon,size},... }
      • [.icon] string - png/jpg/svg file to represent group of pois. @ as first character indicates a file from this package. Anchor will be middle of icon
      • [.size] number - size of icon
  • cb function - callback to be called if click on item. Format cb(event, coord, payload, weigth). coord is coord of icon payload is payload associated to point. weight is number of points aggregated, when clicking on a cluster icon, 1 if single point

Example

let pois = [[48.8,2.3,"Hello world"],[48.5,2.4,"How are you"],[45.2,2.93,"Very well"]];

hm.cluster(pois);

// with more graphic options and callback defined
  let opt = {
   noise: {
         icon: "mcdo.png",
         size: 12
     },
   cluster: {
      200: {
          icon: "@svg/cluster_red.svg",
          size: 64
      },
      75: {
          icon: "@svg/cluster_orange.svg",
          size: 52
      },
      2: {
          icon: "@svg/cluster_green.svg",
          size: 40
       }
   }
  };
 hm.cluster(pois, opt,
          (event, coordinate, data, weight) => {
              if (data)
                  console.log("click on point ", data);
              else
                  console.log("click on cluster with weight", weight);
          });

hm:clusterHide()

Hide cluster layer

Kind: global function

hm:clusterShow()

Show Cluster layer

Kind: global function

hm:config(opt)

To configure app_id, app_code and optionally use CIT and http

Kind: global function
Params

  • opt Object - opt with parameters.
    • [.app_id] string - the app_id from developer.here.com
    • [.app_code] string - the app_code from developer.here.com
    • [.useCIT] boolean = false - true to use CIT environment.
    • [.useHTTP] string = false - true to use HTTP.
    • [.useHTTPS] string = true - true to use HTTPS.

Example

 hm.config({
     app_id: "YOUR APP_ID",
     app_code: "YOUR APP_CODE",
  });

hm:coord2Point([lat,lng]) ⇒ array

Convert [lat,lng] to {lat,lng}

Kind: global function
Returns: array - {lat,lng}
Params

  • [lat,lng] array

hm:coordA2O(arr) ⇒ array

Convert an array [lat,lng] to {lat,lng}

Kind: global function
Returns: array - {lat,lng}
Params

  • arr object - [lat,lng]

hm:coordO2A(obj) ⇒ array

Convert an object {lat,lng} to [lat,lng]

Kind: global function
Returns: array - [lat,lng]
Params

  • obj object - {lat,lng}

hm:coords2XY(coords) ⇒ array

Convert array of [lat,lng] to array of {x,y}

Kind: global function
Returns: array - array of {x,y}
Params

  • coords array - array of [lat,lng]

hm:detour(start, stop, waypoints) ⇒ Promise

Compute the detour for each waypoint provided, compared to normal route from A to B

Kind: global function
Returns: Promise - returns {reference: {start, stop, distance, distance2, time, time2} ,waypoints:[ {coord, distA, timeA, distB, timeB}]}
Params

  • start coord - starting point for route
  • stop coord - destination point of route
  • waypoints array - list of watypoints to test

hm:geocode(address) ⇒ Promise

geocode an address

Kind: global function
Returns: Promise - {coord,body}. coord is geocode as [lat,lng]. body is full json answer
Params

  • address string - address as string

Example

const res = await hm.geocode("avenue des chaps elysees, paris");
console.log (res.coord);

hm:getAvailableMapStyle() ⇒ promise

list of all available map styles normal.day, night....

Kind: global function
Returns: promise - promise with array of {maps,scheme,}

hm:getCenter() ⇒ coord

return coordinate of the center of the map

Kind: global function
Returns: coord - coord of the center as [lat,lng]

hm:getViewBB() ⇒ Object

return bounding box of visible part of map

Kind: global function
Returns: Object - bouding box of visible part of the map, as [latm,latM,longm,lngM]

hm:getZoom() ⇒ number

return zoom value

Kind: global function
Returns: number - zoom level

hm:htmlBounding() ⇒ object

provide bounding box of element hosting map, relatve to window

Kind: global function
Returns: object - {top,left,width, height} relative to window

hm:isoline(opt) ⇒ Promise

compute an isoline. See more info on optional parameters

Kind: global function
Returns: Promise - returns { poly:array, body:object }. Poly is array of coords, body is full answer
Params

  • opt object - option for isoline
    • [.start] coord - coord for starting point of isoline
    • [.destination] coord - coord for destination point of isoline
    • [.rangeType] string = "&quot;time&quot;" - time or distance
    • [.range] number - range in seconds or in meters
    • [.mode] String = "fastest;car;traffic:disabled" - routing mode
    • [.linkattributes] String = sh - attributes to be returned

hm:layerCreate(name, visible)

create a layer

Kind: global function
Params

  • name string - name of layer
  • visible boolean - initial status

Example

hm.layerCreate("layer1");

hm:layerDelete(name)

delete a layer

Kind: global function
Params

  • name String - name of layer

hm:layerEmpty(layer)

Empty a layer, or create it if not existing

Kind: global function
Params

  • layer string

hm:layerFind(name)

find layer by its name or return null

Kind: global function
Params

  • name string

hm:layerSetVisibility(name, visible)

create a layer

Kind: global function
Params

  • name string - name of layer
  • visible boolean - visible or not

Example

hm.layerVisible("layer1",true);

hm:locateMe(callback, opt)

watch position on HTML5 position. This requires HTTPS. Creates layer "_gps"

Kind: global function
Params

  • callback function - callback when coord changes. Format: callback(coord,accuracy)
  • opt Object - optional graphic options
    • [.position] object - graphic options for center. See buildIcon
      • [.svg] string - svg file
      • [.color] string - color for {color} tag
      • [.size] number - size of icon
      • [.anchor] number - anchor of icon
    • [.accuracy] object - graphic options for accuracy representation
      • [.strokeColor] String - color of circle line representing accuracy area
      • [.lineWidth] number - width of line of circle
      • [.fillColor] String - fill color of circle representing accuracy area

hm:map(htmlItem, opt)

create a map area within the specified item

Kind: global function
Params

  • htmlItem string - identifier of html div item on which to insert map
  • opt object - options
    • [.zoom] number = 10 - zoom factor
    • [.center] Coord = [48.86, 2.3] - Coord of the center
    • [.scheme] string = "normal.day.grey" - any scheme defined by HERE, plus "japan", "korea", "black", "white", "transparent". For japan/korea, one needs special credentials as APP_ID_JAPAN APP_KOREA APP_CODE_JAPAN APP_CODE_KOREA
    • [.click] function = - callback on mouse click: callback(coord,button,key)
    • [.dbClick] function = - callback on mouse double click: callback(coord,button,key)
    • [.clickLeft] function = - callback on mouse click left: callback(coord,button,key)
    • [.clickRight] function = - callback on mouse click right.: callback(coord,button,key)
    • [.keyDown] function = - callback on key down : callback(key)
    • [.viewChange] function = - callback if map is panned or zoomed : callback(zoom,coordCenter)
    • [.loadTile] function = - callback when a tile is loaded : callback(z,x,y,url)
    • [.rendered] function = - callback when render is completed : callback(event)

to find all schemes, use hm:getAvailableMapStyle()

Example

const hm = window.heremap;

hm.config({
   app_id: "YOUR APP_ID",
   app_code: "YOUR APP_CODE",
});

hm.map("map", {
   zoom:5,
   center: [48.8,2.3],
   scheme: "satellite.day",
   click: function(coord,button,key) {console.log("clicked on",coord,"with button",button);}
});

hm:marker(opt) ⇒ H.map.Marker

add a marker in a layer svg files can be created with https://editor.method.ac/

Kind: global function
Returns: H.map.Marker - marker created
Params

  • opt object - options to create the marker, can be a coord directly
    • [.layer] string - layer name
    • [.coord] coord - coord of the marker as [lat,lng]
    • [.icon] string - created from hm.buildIcon
    • [.svg] string - see hm.buildIcon
    • [.opt] Object - see hm.buildIcon
    • .pointerenter function - if enter, callback(target,coord,ev)
    • .pointerClick function - if click, callback(target,coord,ev)
    • .data string - optional data
    • .bubble boolean - if true, show buble on click with data
    • .draggable boolean - draggable marker
    • .dragged function - if dragged, callback(target,coord)

Example

hm.marker([48.8,2.3]);

hm.marker({
   coord: [48.8,2.3],
});

hm.marker({
  svg: "svg/marker.svg",
  color:"red",
  ratio:0.5
});

hm.marker({
   img: "http://whatever.com/image.png",
   coord: [48.8,2.3]
});

hm.marker({
   coord: [48.8,2.3],
   data:"Hello world",
   bubble: true
});

hm.marker({
   coord: [48.8,2.3],
   draggable:true,
   dragged: function(target,coord) {console.log("dragged to",coord);}
});

hm:matrix(source, dest, opt) ⇒ Promise

compute a matrix. See more info on optional parameters

Matrix size is limited to 1x100, 100x1 or 15xN

Kind: global function
Returns: Promise - { entries: object, body:object }. entries is the array of {start,stop} information. body is full json answer
Params

  • source object - source as [lat,lng]. Can be array of [lat,lng]
  • dest object - dest as [lat,lng]. Can be array of [lat,lng]
  • opt object - additional optional parameters like mode, summaryAttributes
    • [.mode] string = "&quot;fastest;car;traffic:enabled&quot;" - routing mode to compute matrix
    • [.summaryAttributes] string = "&quot;tt,di&quot;" - attributes in the answer

Example

const res = await hm.matrix({
     source:[48.8,2.3]
     dest:[[48.7,2.5],[48.1,2.0],[44.2,2.3]]
});
console.log (res.entries); 

hm:placeAutoSuggest(opt) ⇒ Promise

Place AutoSuggest @ async

Kind: global function
Returns: Promise - Array of {res,title,value,coord}
Params

  • opt Object - options of autosuggest
    • .search String - search string
    • .center Coord - center search around this coord

hm:point2Coord({lat,lng}) ⇒ array

Convert {lat,lng} to [lat,lng]

Kind: global function
Returns: array - [lat,lng]
Params

  • {lat,lng} array

hm:polygon(opt)

Draw a polygon

Kind: global function
Params

  • opt Object - options to draw a polygon. Same options as hm.polyline

hm:polyline(opt)

Draw a polyline.

Kind: global function
Params

  • opt object - options to draw polyline
    • [.layer] String - optional layer to use
    • [.coords] array - array of coords, as [[48.8,2.3],[48.85,2.4],... ]
    • [.style] object - optional graphic style
    • [.lineWidth] number = 4 - line width
      • [.strokeColor] string = "rgba(0, 128, 255, 0.7)" - line color
    • [.arrows] object - optional arrow
    • [.data] String - optional user data
    • [.pointerClick] function - optional callback if click on line. format callback(target,coord,event)
    • [.pointerenter] function - optional callback if mouse enters on line. format callback(target,coord,event)
    • [.pointerLeave] function - optional callback if mouse leaves the line. format callback(target,coord,event)
    • [.z] number - optional z level
hm.polyline({
   coords: [[48.8,2.3],[48.85,2.4],[48.9,2.6]],
   layer:"layer1"
});

hm.polyline({
   coords: coords,
   style: {
       lineWidth: 4,
       strokeColor: "red"
   },
});

hm.polyline({
   coords: coords,
   data:"Hello World",
});

hm:reverseGeocode(coord) ⇒ Promise

reverse geocode a coordinate

Kind: global function
Returns: Promise - returns { location:object, address:object, body:object}.
Params

  • coord Coord - coord [lat,lng] to reverse-geocode

hm:route(source, dest, opt) ⇒ Promise

compute a route with optional waypooints. See more info on optional parameters

Kind: global function
Returns: Promise - returns { summary: object, coords:array,route: object, body:object}. coords is array of coord, to be used with hm.polyline.
Params

  • source object - source as [lat,lng]. Can be array of [lat,lng] to define waypoints
  • dest object - dest as [lat,lng]. Can be array of [lat,lng] to define waypoints
  • opt object - route options
    • [.mode] string = "fastest;car;traffic:disabled" - routing mode
    • [.routeattributes] string = "waypoints,summary,shape" - route attributes
    • [.maneuverattributes] string = "direction,action" - manoeuver attributes

Example

const res = await hm.route([48.8,2.3],[48.7,2.5]);
console.log (res.summary);

const res = await hm.route([[48.8,2.3],[48.9,2.7]], [49.3,2.5]);
console.log (res.route); 

const res = await hm.route([48.8,2.3], [[48.9,2.7], [49.3,2.5]]);
console.log (res.summary); 

hm:screenshot(opt, opt) ⇒ data

perform a screenshot of the map and returns a promise with the data

Kind: global function
Returns: data - binary data of image
Params

  • opt object - options for screenshot
    • [.name] string - filename for download
    • [.ui] boolean - true to ui (scale, etc..) in screenshot
  • opt object - options for screenshot

hm:setCenter(coord)

set center of the map

Kind: global function
Params

  • coord Array - coord as [lat,lng]
  • @example
hm.setCenter([48.8,2.3]);

hm:setScheme(scheme)

define the scheme. List of scheme can be obtained from hm.getAvailableMapStyle()

Kind: global function
Params

  • scheme string - scheme name

hm:setViewBB(opt)

sets bouding box to be displayed

Kind: global function
Params

  • opt Object | string - either an object specifying how to set bounding box, or a String being the name of a layer
    • [.layer] string - bouding box aroud all objects of the layer
    • [.pois] array - bouding box aroud all coords defined as [coord,coord...]

Example

hm.setViewBB("layer1");

hm.setViewBB({
   pois: coords
});

hm:setZoom(zoom)

set zoom level

Kind: global function
Params

  • zoom number

hm:simplify(coords, tolerance) ⇒ array

Simplify a polyline by using the Ramer-Douglas-Peucker algorithm

Kind: global function
Returns: array - simplified polyline
Params

  • coords array - array of [lat,lng]
  • tolerance number

hm:touch(onoff, options)

activate touch, allowing hand drawing, with embedded simplification of the line

Kind: global function
Params

  • onoff boolean - activate or deactivate
  • options object - options to control the touch behaviour
    • [.callback] function - calling callback(coords) when touch ends
    • [.layer] string - layer where to put the drawing
    • [.style] object - drawing style for the line
    • [.arrow] object - arrow style for the line
    • [.tolerance] number = 4 - tolerance for simplification
    • [.keep] boolean = false - keep graphic or not when calling callback

hm:xy2Coords(coords) ⇒ array

Convert array of {x,y} to array of [lat,lng]

Kind: global function
Returns: array - array of [lat,lng]
Params

  • coords array - array of {x,y}

marker:getCoord() ⇒ coord

get coordinates of a marker

Kind: global function
Returns: coord - [lat,lng]
Example

let m =hm.marker([48.8,2.3]);

let coord = m.getcoord(); // returns [48.8,2.3]

© 2018-2020 devbab

About

A framework to simplify the use of HERE Maps, which a bunch of higher level functions. In addition, it brings geocoding and routing functions to Node.js

Resources

Stars

Watchers

Forks

Packages