JSON configuration - davidmegginson/hxlmaps GitHub Wiki

hxlmaps uses a JSON configuration file to define the map. If you leave some properties blank, hxlmaps will make intelligent guesses about what countries you're working with and what kinds of map layers you want to see, based on your dataset's HXL hashtags and P-codes. A minimum viable configuration file would look like this:

{
    "layers": [
        {
            "url": "https://data.humdata.org/dataset/d7ab89e4-bcb2-4127-be3c-5e8cf804ffd3/resource/b8f708da-e596-456c-b550-f88959970d21/download/mali_3wop_decembre-2017.xls"
        }
    ]
}

You can experiment with different configuration files and see the results interactively at https://davidmegginson.github.io/hxlmaps/widget/setup.html

Top-level properties

Example:

{
    "title": "Mali conficts and 3W",
    "layers": [ ... ],
    "codLayers": [ ... ]
}

Name	Type	Default	Description
title	string	"hxlmap"	The title to display with a standalone map (e.g. in bookmarks).
layers	array	required	List of HXL layers to overlay on the map.
codLayers	array	none	List of COD layers to include as an alternative to OpenStreetMap tiles.

HXL layer properties

A HXL layer is a map overlay based on a HXL-hashtagged dataset. Each object appears as an item in the layers array at the top-level of the hxlmaps configuration file. A map must have at least one HXL layer.

Example:

{
    "name": "ACLED conflict heat map",
    "url": "https://data.humdata.org/dataset/acled-data-for-mali",
    "unit": "incidents",
    "type": "heat"
}

Name	Type	Default	Description
name	string	none	The name to display for the layer.
url	url	required	The location of the HXL data to display.
type	( "areas" | "points")	(guessed based on HXL data)	The type of layer to create.
style	string	(guessed based on HXL data)	The style of the layer ("markers", "cluster", or "heat" for a points layer; always "choropleth" for an areas layer
hashtag	string (HXL tag pattern)	(guessed based on HXL data)	A HXL hashtag pattern matching a column with a number for mapping (e.g. "#affected+refugees"
aggregate	("count" | "sum")	(guessed based on HXL data)	The aggregate function to use: "count" to count the number of rows, or "sum" to add the values in each row.
legend	string	(column text header)	The text to display in the data legend (e.g. "Number of refugees")
unit	string	"items"	The countable unit to list (e.g. "facilities", "activities")
colorMap	object (see Color maps)	(defaults to shades of blue)	For choropleth area maps, the range of colours to display.

COD layer properties

The CODs, or Common Operational Datasets, are fundamental baseline data available for use in humanitarian crises. The official repository of CODs is UNOCHA's Humanitarian Data Exchange. The University of Georgia's iTOS service makes some of the map components of the CODs available online, and hxlmaps takes advantage of these both for producting area-type HXL layers, and for providing an alternative base layer to OpenStreetMap tiles.

You add one object in the top-level codLayers array for each set of boundaries that you want to display on the map. hxlmaps will combine them into a single base layer.

Example:

{
    "country": "MLI",
    "level": "#adm1"
}

Name	Type	Default	Description
country	string (ISO3 country code)	required	The country code of the COD to display.
level	string (HXL hashtag)	"#country"	The admin level to display ("#country", "#adm2", etc).

Full example

{
    "title": "Mali conficts and 3W",
    "layers": [
        {
            "name": "ACLED conflict heat map",
            "url": "https://data.humdata.org/dataset/acled-data-for-mali",
            "unit": "incidents",
            "type": "points",
            "style": "heat"
        },
        {
            "name": "Mali 3W",
            "url": "https://data.humdata.org/dataset/d7ab89e4-bcb2-4127-be3c-5e8cf804ffd3/resource/b8f708da-e596-456c-b550-f88959970d21/download/mali_3wop_decembre-2017.xls",
            "unit": "3W activities",
            "type": "areas"
        }
    ],
    "codLayers": [
        {
            "country": "MLI",
            "level": "#adm1"
        }
    ]
}