Add “City Search” to a Location Question

Overview

SurveyToGo location questions support both online and offline maps. In either mode, you can enable respondents to search for cities and automatically center the map on the selected location. City search uses a SQLite database containing city names and coordinates, which can be generated from OpenStreetMap data or your own Excel/CSV file.

To enable city search:

1. Download a country city data file.

2. Convert the file to SQLite format.

3. Configure the location question to use the SQLite database.

4. Search for cities on the device.

Step 1: Download Country City Data

To download city data from OpenStreetMap:

1. Open the Geofabrik download site: https://download.geofabrik.de/

2. Select the appropriate continent.

3. Locate the country you need and click the corresponding .osm.pbf file.

4. Save the file to your computer.

Note: Country files can be large and may take some time to download.

Step 2: Convert the File to SQLite Format

After downloading the .osm.pbf file, convert it into a SQLite database.

Convert OpenStreetMap Data

1. Download the Dooblo Converter package: LocationQuestionCitySearch.zip.

2. Extract the ZIP file.

3. Copy the downloaded .osm.pbf file into the extracted folder.

4. Open Command Prompt and navigate to that folder.

5. Run:

   1. ProcessPBF.bat <cities-file.osm.pbf>

Example:

ProcessPBF.bat portugal-latest.osm.pbf

When processing completes, a SQLite file such as portugal-latest_cities.sqlite will be created.

Important: Processing large country files may take a significant amount of time.

The generated database includes English city names and up to three additional languages commonly found in the source data. On the device, translated names appear beside the English name in parentheses.

Convert Excel or CSV Files to SQLite

If OpenStreetMap data is not suitable, you can create your own city database.

Prepare an Excel or CSV file with:

• No header row

• Six columns:

  • City name (English)

  • Translation 1

  • Translation 2

  • Translation 3

  • Latitude (decimal format)

  • Longitude (decimal format)

If your file contains non-Latin characters, save it as CSV Unicode before processing.

Use the provided ProcessCSV.bat utility to generate the SQLite database.

Example:

ProcessCSV.bat MyCities.csv French Arabic German

This creates MyCities.sqlite.

If translation columns are empty, you must still provide placeholder language names in the command.

Step 3: Configure the Location Question

After creating the SQLite file, configure the location question to use it. There are two supported methods:

Option 1: Copy the SQLite File to Devices

This approach is recommended for SQLite files larger than 15 MB.

Advantages:

• Faster deployment of large files

• Faster survey synchronization

Limitation:

• Files must be distributed manually.

To configure:

1. Copy the SQLite file to the device.

2. Add a Location question.

3. Enable Use Cities Search.

4. Set Cities Source to New.

5. Click the + button to create a new attachment source.

6. Use the following script:

   1. list.Add("$ROOT$/Portugal-latest_cities.sqlite","1");

Replace the filename with your SQLite file.

7. Name the attachment source and save it.

8. Select the new source from the list.

Option 2: Attach the SQLite File to the Survey

Advantages:

• SurveyToGo automatically distributes the file to devices.

Limitations:

• Slower synchronization

• Uploads of files larger than 15 MB may fail.

To configure:

1. Select the survey root.

2. Open the Advanced tab.

3. Click Edit Survey Attachments.

4. Select New.

5. Click Add Files and choose the SQLite file.

6. Click Upload.

After the upload completes:

1. Add a Location question.

2. Enable Use Cities Search.

3. Set Cities Source to New.

4. Click the + button to create a new source.

5. Use the following script:

list.AddFromAttachment("portugal-latest_cities.sqlite");

Important: This syntax differs from Option 1. Do not use list.Add() when referencing survey attachments.

6. Name the source and save it.

7. Select the newly created source.

Step 4: Search for Cities on the Device

After synchronizing the survey:

1. Open the interview.

2. Navigate to the location question.

3. Tap Open Map.

4. Begin typing the city name.

After entering at least two characters, matching cities will appear. Select a city from the list to automatically center the map on that location while preserving the current zoom level.