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
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);}
});
See under directory demo:
- demo-basic.html: how to display a simple map in a web pgae
- demo-cluster.html: how to cluster thousands of points on a map
- demo-markers.html: different kind of svg or png markers, with different size, anchor..
- demo-screenshot.html: how to do a screenshot of the map
- demo-asia.html: how to display high quality ap in Japan and Korea. (requires special credentials)
- demo-autocomplete.html: autocomplete exemple
- demo-touch.html: draw a polyline on a touch screen
- demo-nearcity.html: find big cities around the mouse click
- demo-locateme.html: display own location
- 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
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
hide a unique bubble
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
- [.size]
- [.img]
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"
}
});
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
- [.strokeColor]
- [.layer]
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
- [.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
- [.icon]
- [.minZoom]
- cb
function
- callback to be called if click on item. Format cb(event, coord, payload, weigth).coord
is coord of iconpayload
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);
});
Hide cluster layer
Show Cluster layer
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.
- [.app_id]
Example
hm.config({
app_id: "YOUR APP_ID",
app_code: "YOUR APP_CODE",
});
Convert [lat,lng] to {lat,lng}
Kind: global function
Returns: array
- {lat,lng}
Params
- [lat,lng]
array
Convert an array [lat,lng] to {lat,lng}
Kind: global function
Returns: array
- {lat,lng}
Params
- arr
object
- [lat,lng]
Convert an object {lat,lng} to [lat,lng]
Kind: global function
Returns: array
- [lat,lng]
Params
- obj
object
- {lat,lng}
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]
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
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);
list of all available map styles normal.day, night....
Kind: global function
Returns: promise
- promise with array of {maps,scheme,}
return coordinate of the center of the map
Kind: global function
Returns: coord
- coord of the center as [lat,lng]
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]
return zoom value
Kind: global function
Returns: number
- zoom level
provide bounding box of element hosting map, relatve to window
Kind: global function
Returns: object
- {top,left,width, height} relative to window
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
= ""time""
- 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
- [.start]
create a layer
Kind: global function
Params
- name
string
- name of layer - visible
boolean
- initial status
Example
hm.layerCreate("layer1");
delete a layer
Kind: global function
Params
- name
String
- name of layer
Empty a layer, or create it if not existing
Kind: global function
Params
- layer
string
find layer by its name or return null
Kind: global function
Params
- name
string
create a layer
Kind: global function
Params
- name
string
- name of layer - visible
boolean
- visible or not
Example
hm.layerVisible("layer1",true);
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
- [.svg]
- [.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
- [.strokeColor]
- [.position]
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)
- [.zoom]
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);}
});
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)
- [.layer]
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);}
});
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
= ""fastest;car;traffic:enabled""
- routing mode to compute matrix - [.summaryAttributes]
string
= ""tt,di""
- attributes in the answer
- [.mode]
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);
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
- .search
Convert {lat,lng} to [lat,lng]
Kind: global function
Returns: array
- [lat,lng]
Params
- {lat,lng}
array
Draw a polygon
Kind: global function
Params
- opt
Object
- options to draw a polygon. Same options as hm.polyline
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
- [.strokeColor]
- [.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
- [.layer]
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",
});
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
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
- [.mode]
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);
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
- [.name]
- opt
object
- options for screenshot
set center of the map
Kind: global function
Params
- coord
Array
- coord as [lat,lng]
- @example
hm.setCenter([48.8,2.3]);
define the scheme. List of scheme can be obtained from hm.getAvailableMapStyle()
Kind: global function
Params
- scheme
string
- scheme name
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...]
- [.layer]
Example
hm.setViewBB("layer1");
hm.setViewBB({
pois: coords
});
set zoom level
Kind: global function
Params
- zoom
number
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
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
- [.callback]
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}
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