Component API calls

These are the functions you can call on an OpenHeatMap object from Javascript within a page. The object itself should be retrieved by calling getOpenHeatMap() from the supplied openheatmap.js script.

addInlay(leftX, topY, rightX, bottomY, topLat, leftLon, bottomLat, rightLon)

Creates an inlay that renders an area of the map over the top of the main view. This is typically used to display places like Alaska or Hawaii on a map of the US, but is also useful for showing details like a zoomed-in view of a city center on a regional map. One pitfall to beware of is that the first four values are coordinates in screen pixels for the area where the inlay should appear in the current view, so you should only call this directly after setting the initial viewing area, before the user has had a chance to zoom and pan.

getLatLonViewingArea()
returns { topLat: , leftLon: , bottomLat: , rightLon: }

Returns the latitude and longitude at the corners of the current viewing area. If the user hasn’t panned or zoomed, these should be identical to the values previously set with setLatLonViewingArea, otherwise they’ll reflect the user’s changes.

getPixelsPerDegreeLatitude()
returns Number

The result of the function is the vertical scale factor of the current view. For example, if it’s 4.0, then you’d need a map (4*180) or 720 pixels high to represent the full range of latitudes from Antarctica to the North Pole. Because latitudes increase as you head north, and the component uses a vertical axis where zero is at the top and larger values represent lower pixels, this is usually a negative value.

getValueForWayId(wayId)
returns Number | null

If the map is displaying data specifying values for individual areas, then this function will return the value associated with a particular area. The input ID is typically received from an event callback telling you which ways the user is mousing over. If the map is animated then the value will be from the current frame being displayed. If no value is set, then null will be returned.

getValuePointsNearLatLon(latitude, longitude, radius=0)
returns [{value: }, …]

If the map is displaying data as a density map of individual points, this will return an array containing the values of points within the radius of the specified point. If no points are nearby, it will return an empty array.

getWayForWayId(wayId)
returns {id: , nds: [], tags: {} }

Given the identifier of a way, this will return the full information for that way. This closely follows the OpenStreetMap XML format, with the nds array specifying nodes within the main list, and tags containing the key/value pairs holding information about the way. This can be useful if you want to pull common tags like ‘name’ for a node that the user is mousing over.

getWaysContainingLatLon(latitude, longitude)
returns [{id: , nds: [], tags: {} }, …]

Returns a list of the ways that this point lies within. For closed polygons (where the last node is the same as the first, and drawn as a filled area) this accomplished with a simple intersection test. For unclosed polygons (where the last node is not the first, and drawn as a series of connected lines) the test is done against a thick line, with the thickness controlled by the line_thickness property of the way. The format of each way in the list is the same as for getWayForWayId()

loadValuesFromCSVString(csvString)

Use this function to load in values to display on the map from a string containing a header row of labels separated by commas, followed by a newline, then a series of rows specifying values for each label with each value separated by commas and each row separated from the next by a newline. The labels should include a location header (see What kind of locations does OpenHeatMap understand? ) and possibly a value and other columns.

loadValuesFromFile(url)

This function is identical to loadValuesFromCSVString() except that it loads the values from the network resource specified by the input URL rather than directly from a string containing the data.

loadWaysFromFile(url)

Loads the polygons and lines that define the map. The file should be in the OpenStreetMap XML format, and if you want to color the different areas using values from the data you’ll need to include key/value pairs in the tags that correspond to location headers in the data. For example if you create an OSM XML file containing the areas covered by each US zip code, and you have a CSV file with ‘zipcode’ as one of the columns, then your ways will need to identify them.

removeAllInlays()

Gets rid of all the inlays in the current map. You should call this to reset the map if you’re switching over to a completely new view, to remove any inlays left over from the previous one.

removeAllWays()

Deletes all the current polygons and lines from the map. You’ll usually call this before you load a new set of ways into an existing map.

setColorGradient(gradient: [])

Sets the color scale used to display the values on the map. It’s specified as a variable length array of color strings, eg setColorGradient([‘#000000’, ‘#FFFFFF’]); will create a black-to-white gradient.

setEventHandler(eventName, functionName)

Tells the component to call the user-supplied function whenever the specified event occurs. For a full description of the possible events see Events list

setGradientValueRange

setLatLonViewingArea

setOceanColor

setPixelsPerDegreeLatitude

setSetting

setSize

setWayDefault

translateMapByScreenPixels

zoomMapByFactorAroundPoint