AreaMapper (Docker)

AreaMapper is a tool which can help you prepare your business data for use in the CleverMaps platform. AreaMapper computes geometric intersection between points and polygons (areas) and then adds ID's of polygons to the points table if an intersection exists. Example scenario could be mapping points of your customers to administrative units. Then you can calculate metrics of your customers in context of city districts, cities, counties and so on (e.g. count of customers in each city).

You can map points to your own area data (e.g. delivery zones) or you can use already prepared data dimension from us (e.g. administrative units). Both points and areas need to have the same coordinate system (e.g. WGS84).

AreaMapper is CSV based (input and output), geometry of points has to be stored in latitude/longitude columns, geometry of polygons has to be stored as WKT string (https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry).

Installation

AreaMapper is distributed as a Docker image so you need to have Docker platform installed. You can get Docker here.

AreaMapper is publicly available on Docker hub: https://hub.docker.com/r/clevermaps/areamapper

Use following command to get the image:

CODE

docker pull clevermaps/areamapper:latest

Running AreaMapper

There are few steps you need to do before running AreaMapper:

Create an empty directory on your local drive (e.g. /home/user/clevermaps/areamapper).
Copy your CSV file with points you would like to map into the folder. Optionally copy also your CSV file with areas.
Create a configuration file for AreaMapper and save it as a JSON file into the folder. Please check the examples below in Configuration to get the idea how the configuration file should look.

Use following command to run AreaMapper:

CODE

docker run -t -v /home/user/clevermaps/areamapper:/workdir clevermaps/areamapper:latest --config /workdir/config.json

! Change /home/user/clevermaps/areamapper to your directory path !

Configuration

Mapping to your own areas

In this case you need two CSV files - one file with point geometry stored in X (longitude) a Y columns (latitude) and one file with areas geometries stored as WKT polygons. Points could be orders and areas could be cities for example.

CODE

{
    "input_points": {
        "filename": "/workdir/your_file_with_points.csv",
        "delimiter": ",",
        "geom_fieldname_x": "x",
        "geom_fieldname_y": "y",
        "join_fieldname": ""
    },
    "input_areas": {
        "filetype": "csv",
        "filename": "/workdir/your_file_with_areas.csv",
        "geom_fieldname": "wkt",
        "primary_key_fieldname": "id",
        "delimiter": ",",
        "join_fieldname": ""
    },
    "output": {
        "filename": "/workdir/your_output_file_name.csv",
        "delimiter": ",",
        "not_matched_value": "0"
    },
    "temp_directory": "/workdir"
}

Mapping to already prepared areas from us

In this case you only need one file - your points data. Areas are automatically and temporary downloaded from cloud storage.

CODE

{
    "input_points": {
        "filename": "/workdir/your_file_with_points.csv",
        "delimiter": ",",
        "geom_fieldname_x": "x",
        "geom_fieldname_y": "y",
        "join_fieldname": ""
    },
    "input_areas": {
        "filetype": "candim",
        "filename": "can-dim-zsjd"
    },
    "output": {
        "filename": "/workdir/your_output_file_name.csv",
        "delimiter": ",",
        "not_matched_value": ""
    },
    "temp_directory": "/workdir"
}

Parameters description

input_points.filename: Full path to the input CSV file with points to map. E.g. '/home/user/data/points.csv'.

input_points.delimiter: Delimiter used in CSV file.

input_points.geom_field_x: Name of the column which contains X coordinates (longitude). E.g. 'lng' or 'x'.

input_points.geom_field_y: Name of the column which contains Y coordinates (latitude). E.g. 'lat' or 'y'.

input_points.join_fieldname: Name of the column which contains a key to pair with areas (optional). If specified than only points and areas with same values of the key column are compared.

input_areas.filetype: Available values are 'csv' or 'candim'. If you are mapping to your own file with areas data then set value to 'csv'. If you are mapping to already prepared data dimension from CleverMaps then set value to 'candim'.

input_areas.filename: In case of input_areas.filetype = 'csv' set full path to the file with area data. In other case input_areas.filetype = 'candim' set name of CleverMaps data dimension. Available dimensions are:

can-dim-zsjd-cz (Neighborhoods of Czech Republic).
can-dim-zsj-sk (Neighborhoods of Slovakia)
can-dim-zipcodes-us (Zipcode of United States)
can-dim-lau-eu (Local Administrative Units of European union)
can-dim-settlements-hu (Settlements administrative units of Hungary)
can-dim-obwod-pl (Obwod administrative units of Poland)
can-dim-grid-uber-9-cz (Hexagonal grid by Uber for Czech Republic)
can-dim-postcodes-cz (Postcodes of Czech Republic)
more information about data dimensions here Data dimension projects

input_areas.delimiter: Delimiter used in CSV file. Set only in case of input_areas.filetype = 'csv'.

input_areas.geom_fieldname: Name of the column which contains geometries of areas. Set only in case of input_areas.filetype = 'csv'.

input_areas.primary_key_fieldname: Name of the column which contains primary key of areas. These values will be mapped to points. Set only in case of input_areas.filetype = 'csv'.

input_areas.join_fieldname: Name of the column which contains a key to pair with points (optional). If specified than only points and areas with same values of the key column are compared. Set only in case of input_areas.filetype = 'csv'.

output.filename: Full path to the output CSV file. E.g. '/home/user/data/points_areas.csv'.

output.delimiter: Delimiter to use in output file. E.g. '0'.

output.not_matched_value: Default value of area primary key for not matched rows