1. Home
  2. XLSForm Authoring
  3. How to use OpenStreetMaps in OpenMapKit
  1. Home
  2. Data Collection
  3. How to use OpenStreetMaps in OpenMapKit

How to use OpenStreetMaps in OpenMapKit


OpenStreetMap (OSM) is a collaborative project used to create a free editable map of the world. OSM goes beyond an open alternative to Google Maps, but to potentially the canonical source for shared locations. GPS points are great for creating a dot on the map, but by selecting an OSM feature in your form, you have an advantage of referencing the location of the survey to a unique identifiable OSM geographical feature on a map such as a town, health facility or road with OSM instead of a GPS point.

OpenMapKit (OMK) is a third-party Android app that provides the capability to associate an OSM feature with your form to edit tags of OSM features. OpenMapKit integrates with ODK Collect similar to how a barcode question would activate a barcode application to capture the barcode. In this case, OpenMapKit will display an OSM map and allow you to select ways or nodes. During a survey, when a user gets to an OSM question, they will click on the launch OpenMapKit button. This will open OpenMapKit with an OpenStreetMap map. OMK will allow the user to select an OSM way (which could either be an open way, for instance a road, or a closed way, for instance a building) or node (a single point). Once the OSM feature is selected, the tags associated with the feature will be available for editing. The user can then make edits on the tags of interest accordingly or simply select the feature by clicking on the check mark. The OMK feature is then attached to the submission question as a file which includes the OSM XML of the selected OSM feature and tags associated to that feature.

Note: To use OMK, you will need to install the latest release of ODK Collect and the Ona version of OMK on your device. For more information about both tools, please see the following documentation for ODK Collect and OMK.

Differences between the Ona OMK and Google Play Store OMK App

The OMK app on the Google Play Store is maintained by the American Red Cross. The Ona version of OMK was forked from the Google Play Store app, and it allows you to control different settings by uploading a JSON settings file as a form media file.

OMK Components

To use OMK, you will need nodes (i.e. points) or ways and a basemap. The points will be generated from an osm file. The basemap can be the Online Humanitarian OpenStreetMap, which requires an internet connection, or you can create your own basemaps, such as mbtiles, which allow you to collect data offline. Using your own basemap may require a large amount of storage on your mobile device. If the basemap is too large, you may need to break down your basemap into smaller mbtiles, and load corresponding section of a basemap to mobile devices individually that are collecting data in the associated location.

How to Author and Answer Questions Using OpenMapKit

How to add OSM questions to XLSForms

An OSM question is a new “media type” question. It functions in the survey in a similar manner as photo or video questions, the user is asked to launch the phone camera. In the same way, when OSM question is specified in a survey, ODK Collect opens/launches OMK, and it provides parameters for the tags to be entered for an OSM feature that is selected.

The following steps will show how to add an OSM question to XLSForm. The Basic OpenMapKit XLSForm is used as an example.

Step 1

In your form, you will have an extra sheet called osm, different from the survey, choices and settings sheets. The osm sheet generally defines the tagging parameters that will be sent to OMK. On the survey sheet (as shown below), your reference question is named building_tags. In the type column, it has a parameter of building_tags. This parameter is referenced in the osm sheetThe osm sheet defines only the tags you are interested in the OSM features. An OSM feature may have many more tags that you will not be interested in. It also may specify custom tags that you will want included in the OSM feature.

Step 2: How to add osm tags

As mentioned earlier, in the survey sheet, your osm_building question had a type parameter called building_tags. In the osm sheet, we have several rows with parameters of building_tags, or questions asked when OMK is launched, in the list name column.

list name has two functions:

  • It defines the set of tags, or questions asked, that OMK will add to an OSM feature. The set of OSM tags has a list name suffix of _tags. The values in the name column are the tag keys that are recognized in OSM. The values in the label column are the labels that will be presented to the user when entering choice values for the given OSM tag.
  • It defines the set of tag values, or choices, selectable for a given OSM tag, or question. (optional) This functions at a time when you do not want the user directly typing in values for an OSM tag. Typing in a specific string value is error prone; and if there is a set of possible values that we want for a given tag, then these values can be presented as a multiple choice question to the user.


Here notice that one of the building_tags has a name called building.

If you want to provide multiple choice values for a building tag to the user, then you need to include the corresponding tags in the osm sheet as shown below.  The name column value associated with a OSM tag is added below in the list name column. Each multiple choice option is added in the name column, which is associated with the same list name and its respective label. This is done for each of the multiple choice tags.

The multiple choice values for the building tags will appear on OpenMapKit as follows:

If you don’t provide multiple choices values for a tag (e.g. as for addr:street in our reference XLSForm)

then, the user will be required to manually type in a value for a given question. On OpenMapKit, the question for the building tag where a user manually types in a value will appear as below:

OSM files

An OSM file is an XML format file that contains geographic data in accordance with the OSM API. This geographic data can include: buildings, streets, offices, geo-locations, etc.

Generating an OSM File

There are different ways that you can generate an OSM file. This section will cover one method, using a CSV file and JOSM:

Install JOSM

  1. You will need to download the JOSM application. JOSM is a free desktop software to edit OSM geodata.
  2. Open JOSM.
  3. Open the Preferences:
    1. On PCs, under the Edit menu, scroll to the bottom and click Preferences.
    2. On Macs, under the MainApplication menu, click Preferences…
  4. The Preferences pop-up window will appear.
  5. Click the on Plugins, the fourth icon from the top.
  6. In the Plugins search bar, type opendata.
  7. The plugin should appear. Check the box next to the found plugin and click Download list.
  8. Click OK.
  9. Close the JOSM Application and reopen it.
  10. Repeat Steps 3 through 6 to ensure the plugin is included.

Generate the CSV

  1. Either download data from a form in Ona with geodata or save a CSV file with geodata to your local machine.
  2. In the CSV file, please make sure the GPS coordinates have one column with latitude named lat and one column with the longitude named lon. (Optional) You can also include other properties/columns/data you want by including these fields in the CSV. Please note these optional fields will appear as tags, or questions when OMK is launched. Delete all the other columns, if applicable.
  3. Please ensure you save the file with any optional fields as a CSV.

Generate an OSM using the CSV

  1. Open JOSM
  2. In the Menu bar, click File > Open. Select the CSV you just generated. Click Open.
  3. Leave the projection method as the default WGS84 Geographic and click OK.
  4. Once the file loads, depending on the size, you should see light green points. To ensure they are visualizing as expected, you can select a map to visualize the points on by selecting the map from the Imagery menu. I would recommend the OpenStreetMap Carto (Standard).
  5. Go to the menu, click File > Save as. The default save format is .osm. The file name is the same as the CSV file. You can change the file name, but leave the format as .osm.
  6. To open or load these filed, you will need to copy them inside the osm folder in side the openmapkit folder on your mobile device.

Add a version, changeset, and timestamp to your OSM file

  1. Open the newly generated OSM file using a text editor. For PCs, we recommend Notepad++. For Macs, you can use TextEdit.
  2. Then, go to the Edit menu and navigate to the Find and Replace.
  3. In the Find text box, enter `<node`
  4. In the Replace text box, enter something similar to `<node changeset=’1′ version=’1′ timestamp=’2018-04-17T10:00:00.999Z`.
    1. For the timestamp, enter today’s date in the format `YYYY-MM-DDTHH:MM:SS.SSSZ`.
      1. YYYY is the year
      2. MM is the month
      3. DD is the day
      4. HH is the hour
      5. MM is the minutes
      6. SS.SSS is the seconds
  5. Save the file.

How to copy OSM files to OpenMapKit App directory

In some situations, you can download files where there is network or a wifi connection. However, with our method used to generate the OSM files, user will have to manually add their OSM files to their mobile devices.

Below is a step-by-step procedure on how to add OSM files manually to your OMK App Directory folder located in your phone or tablet:

For OS X system:

  • Connect your phone/tablet to your computer or laptop using a USB cable;
  • Locate/search for the Android File Transfer and double click to open;
  • Double click on the openmapkit folder;

  • Double click on the osm folder;

  • Drag and drop all of your osm files into the folder.

For Windows system

  • Connect your phone/tablet to your laptop or computer using a USB cable;
  • Open the mobile device storage, then double click on openmapkit folder;   

  • Double-click on the osm folder;

  • Copy and paste all the files into the folder:

Using OSM forms in ODK Collect

Below, you can see a step-by-step user interface (UI) iteration of an OSM form question.

  1. Tap on Launch OpenMapKit for an OSM question.

  1. Select complete the action using OpenMapKit.

  1. Tap on the Gear Icon, and click OSM XML Layers from the dropdown.

  1. Select the desired osm file. In this example, it is the kilimani.osm file. Click OK.

  1. Tap on a specific point or structure on the map to launch the point or structure’s tags. In this example, select the build to launch the building tags.   

  1. To edit a tag, tap on a specific tag.

  1. Once you have finished filling all the point or structure’s tags, click Save.

If you need to edit the tag again once you have saved it, you can select Redo OSM Tagging and repeat the previous steps.

Configuring the OpenMapKit settings and constraints

When the OpenMapKit is started for the first time, it creates a folder named openmapkit within the device files. The openmapkit folder has three sub-folders in it: osm, mbtiles and settings. These sub-folders are used to store files needed by the application.


When you use the Ona version of OMK, there are additional settings you can include, that are not available in the Google Play Store version of OMK. These settings include the following:

Minimum Zoom to Render Points/Structures

In OMK, certain points or structures will only visible at a certain zoom level. If you are zoomed too far out or too close, the points or structures may be visible on the map. This setting allows you to determine at what zoom level the points are renderable. An example can be seen below.


 “min_vector_render_zoom”: 8


Syncing Data from Ona:

This feature allows you download filtered OSM data from submissions on Ona. You can only fetch OSM data from forms that had OSM data collected.

In a project which uses OMK to determine which houses in an area have received Indoor residual spraying (IRS), this feature allows you see which other house in the area have already been tagged by others. For example, the form to determine if the house received IRS is being used by 300 people, data is collected, and then all the data is submitted. When you use this feature, you would not want to fetch all the OSM data from the form, but you would probably want only a filtered portion of the data or it might be too much data. An example can be seen below.

 “osm_from_odk”: {

“query”: “health_facility”,

“forms”: [244266,44332]

“server”: “https://api.ona.io/api/v1/data/”,

“username”: “myusername”,

“password”: “mypassword”


In this specific element:

  • query is the filter. It specifies the field a user is using from the OMK data collected. The person collecting the data will be asked for the specific value during when they are doing the sync.
  • forms specify which forms you want to sync using the pk value. You can use multiple form. The pk value can be found form the URL. For example, in the URL https://ona.io/acme/2280/18477, the pk value is 18477, or the last number in the URL. The forms are separated by a comma (,) in the square brackets.
  • username and password are Ona account credentials which have at least “can view and download” permission levels in those forms.
Rename OSM Nodes/Points

OSM allows you to collect points, or nodes, lines, or an open way, and structures, or closed polygons. You can only add points. This feature allows you to determine what a node will be called. An example is shown below, which essentially changes a node to be called a Water Point.

“node_name”: “Water Point”

Hide options

Certain options in the upper corner can be hidden. The default is all options are showing. The options to be hidden are phrased exactly as they are displayed in the menu and are case insensitive. An example can be seen below.

“hidden_menu_items”: [


“osm xml downloader”,



User Location Tags

Each point or structure has tags, or associated questions. Some of these tags are hidden, like metafields. User location tag, or associated questions, that can be collected include:

    • A user’s longitude and latitude at the time of selecting a point or structure
    • A user’s GPS accuracy at the time of selecting a point or structure
    • A user’s distance from the centroid of a point, line, or structure of the selected point or structure at the time of selecting the point or structure.

An example is shown below.

“user_location_tags”: {

“lat_lng”: {

  “name”: “userlatlng”,

  “label”: “User Location”


“accuracy”: {

  “name”: “useraccuracy”,

  “label”: “Location Accuracy”


“distance”: {

  “name”: “userdistance”,

  “label”: “Distance From Structure”



Clickable Tags

Normally, you can click on tags and it will show all tags, or you can go to a specific tag. If you click a middle tag, you would have to scroll back to answer previous tags and forward again. If you are utilizing the require constraint, you would not want them to click on a middle tag. This feature will turn off the capability to click any tag. It can be false or true, and it is case sensitive. You will want it be false, if you don’t want someone to click any tag, including middle tags. An example is given below.

“clickable_tags”: false

Admin Password

The admin password prevents data collectors from doing certain “admin” tasks: collecting data when the GPS is off or changing the admin password. An example can be seen below.

“admin_password”: “password1234”

Location Shifting Strategy

There are two ways that Android device can collect geodata:

1. It directly connects to a GPS chip in the mobile device. An example is shown below.

“location_strategy”: “location_manager”

2. Google provides an API around GPS trips.

  • This method will be faster than connecting directly to the GPS chip, but at times it can be inaccurate, especially if the device is in an area with poor connectivity or has just been turned on. It is also continuously asking for a cached position. See the example below.

“location_strategy”: “google_play_services”

Proximity circle

You can include a proximity circle, which shows a circle around the point or structure. By default, this circle shows the GPS accuracy. The more accurate the GPS, the smaller the circle. However, some people prefer this proximity circle to mean the radius of which you are allowed to select points or structures, but the GPS Accuracy will still show in the upper left corner.

In this specific element:

  • proximity_check checks whether the user is in the proximity of the point or structure enabling them to click on the point or structure. false allows a data collector to tag the point or structure regardless of their distance to it.
  • proximity_radius is the radius (in meters) that a data collector needs to be within to the point or structure to click on it.
  • max_gps_timer_delay is a delay timer that is included part of the proximity circle. GPS can take some time to narrow down the exact location. This timer allows you to determine the amount of time (in seconds) that a person clicking on a point or structure must wait before clicking on tags, or questions associated with a point or structure.
  • gps_proximity_accuracy is the minimum accuracy allowed before a data collector can answer tag associated with a point or structure.

An example can be shown below.

“proximity”: {

“proximity_check”: true,

“proximity_radius”: 25,

“max_gps_timer_delay”: 30,

“gps_proximity_accuracy”: 25


Building the OSM Setting Files

The settings are in JSON format. All setting files must be included in one file with the file name: omk-settings.json. An example of a settings files can be found here.


When you use the Ona version of OMK, there are additional constraints you can include, that are not available in the Google Play Store version of OMK. Most of the constraints are related to the tags, or questions for each point or structure, meaning the constraint has to be applied to each tag for it to be reflected on OMK. For example, multiple tags will have the same constraints. These constraints include the following:


The color of the point or structure can be controlled based on the value of a tag, or question. It can be used for when a value has changed. For example, in the previous example of IRS spraying in houses, a red structure could be an unsprayed structure, and a green structure could be a sprayed structure, which was determined by a tag, or question, asking the spray status of the node.

And example is shown below. In this specific example tag:

  • spray_status is the specific osm tag determined in the XLSForm,
  • notsprayed, sprayed, noteligible are tag options, or question choice options.
  • The color, such as #ffff0000, uses hex coloring code
  • The last line after the tag options (“”) denotes the default coloring.


      “colors”: {







Hide tags

Similar to hiding option in the settings, you can also hide tag. The default is false.




Not selectable if

A structure tag, or question, can change from nothing to value, and then never be possible to tag again based on the value type of the tag. For example, using the IRS spraying again, if a structure is sprayed, you can prevent a person from selecting that structure again.

The value in the square brackets (“sprayed”) is the tag option, which when selected for the tag option spray_status, will mean that point or structure can not be selectable.


      “not_selectable_if”: [“sprayed”]



You can set certain point or structure tags, or questions, as required. The default is false.





There are additional constraints that one can include. These can be found on the OMK constraints page.

Building the OSM Constraint Files

The OSM constraints file is in JSON format. All constraint files must be included in one file with the file name: omk-constraints.json. An example of a constraint file can be found here.

Once you have developed your settings and constraint files, you will want to upload them as media files on your OMK form.


Related Articles