Tutorial 1: Find and prepare data

The first step on getting data displayed on your mobile app is actually to get the data, and make it compliant with the converter.

How to find data ?

This can be achieved in various ways : you may already have some data you'd like to put on a map (such as a spreadsheet or a list of places), or you can get existing files on data portals. All you need is data that contains a location or an address.

• Easiest way is to check an open data portal, and get CSV or Excel files from there. You can start by browsing these portals :
  • Citadel Data index : http://www.citadelonthemove.eu/en-us/opendata/opendataindex.aspx
  • Belgium : http://data.gov.be/datasets
  • France : http://www.data.gouv.fr/
  • UK : http://data.gov.uk/data
  • Tip: Try to search for "Data" + your city or location to check if there are data in your area
• You can also get a file from your city, association, or made by yourself. In that case you need to ensure that it doesn't contain personal data and that your are allowed to publish it (but that's another topic).

How should the data look like ?

Once you've got your data file, you need to check that it meet the (few) pre-requisites so you will be able to convert it. Note this is really the trickiest part of the process, as having the rest of the process is pretty straight-forward.

• The data format should be whether CSV or XLS or XLSX (Excel). If you have a spreadsheet or table data in an other format (or web), you may have to "Export" or "Save as" Excel or CSV format. Most softwares and also databases will allow you to do that, including online editors such as Google Spreadsheet or Zoho.
• Ensure that you have some basic fields which will be helpful when you will want to display your data : a title and description for each element is fine to start (you could also include addresses, time information, or any other data). An nice field to add would be a "Category" field", as it will allow you to filter various data in the resulting app, and let user choose to display only markers for one specific category.
• Ensure that you have geographical coordinates in your file, that is "latitude" " and "longitude" or "LatLong" or "Geo-something", which contains numbers like "48.12345", or "48.12345,2.32105". That may sound like a tricky part, but if you have only addresses there are many tools around the web that will let you easily and freely convert adresses to geographical coordinates : that process is called geocoding. Here we will assume that your data does have this information, as there are many tutorials around the web to help you add it to your data have it if it doesn't have it already.
• Ensure that you have an "ID" for each line : an ID is basically a number which can be no more that a line number. All is required is having a different ID for each line, because only data with a unique ID will be displayed. So if there is no ID yet, just add a new column, name it "ID" or "unique number" (at your convenience), and put a line number in each field. If you're using Excel or LibreOffice, put "1" in first field, then write "=1+" in next field below, and select the "1" field. Then copy-paste that field to the whole column so that it automatically fills all IDs.

Troubleshooting tips

Character encoding

• If you experience problems with accents (é, ù, ß, etc.), your file may be encoded in something else than UTF-8. What you need is to save it using UTF-8 encoding (also known as Unicode) which is the world standard, and that will make it compatible anywhere. The process may differ depending of used software, but it's usually available as an option while saving the file.
• The dataset must be encoded in UTF8 (UCS Transformation Format – 8bit) to properly handle all characters. When using CSV, make sure to export using UTF8 or use an external tool before attempting to convert the file. When using Excel, use the xlsx format if possible since it is more up to date; otherwise save as CSV and ensure UTF8 coding from there.

Completeness of the file

All of the fields required by the JSON schema must be filled in every row:

• An ID,
• POI title,
• POI category,
• POI geographical coordinates,
• POI address.

Latitude and Longitude

The coordinates in the original file must be in one of two ways:

1. Latitude and longitude can be in two separate columns. In this case, the Citadel JSON format can be “created” by first dragging “Latitude”, then dragging “Custom text” and typing in a space, finally dragging “Longitude”.
2. Otherwise the original file can already contain the correct formatting, namely latitude and longitude separated by a space. In this case you simply drag “Geographical Coordinates”.

Any other formatting (ie separated by a comma, a semicolon or whatever) will not work since it is not recognized by the Citadel JSON schema.

Coordinate values

The coordinates can be without a sign or with a minus sign, and can range from -90 (or -90.0 or -90.00) until 90 (or 90.0 or 90.00) and, in a similar fashion, from -180 to 180, with any number of decimals. Note that coherence with these values is checked during validation (not during conversion) and if there is an error it is not possible to download (or upload) the file.





Tutorial 2: Convert your data

Converting process

Use the Citadel table to JSON Converter tool to convert your CSV or XLS files into Citadel JSON that will be directly usable into your apps (see Converter tutorials, FAQ and How-tos)

Watch a screencast that demonstrate how to use the converter (Quicktime required)

Note : there are some less visible features or useful tips to make the most out of the converter. Here are a few common tips, but please refer to the Community forum and FAQ for detailed documentation and discussion.

• The conversion process is a 2-step process : first step is the fields mapping, which associates the CSV columns to a list of fields used by the Citadel mobile application templates. The second step let's you complete the metadata fields (licence, author, etc.), and define in more details which fields should be used to display information on the mobile application. E.g.: This way you can use several field in marker popups by adding them to the Description field.
• Geographical coordinates : if you have 2 separate "latitude" and "longitude" fields, you will need to "merge" them at step 2. To to that, drop the latitude field into the Geo coordinates, then drop the longitude field.

Sample files

These files all come from real life situations in each of the four pilot cities. Each file introduces something a little new so users can learn different functionalities one at a time.

• 1. Sortir le soir à Issy: this is a classic demo file that converts smoothly, with geographical coordinates in one column
• 2. Galleries in Athens: this file (that required a bit of reworking since the original is full of null values) has latitude and longitude in two separate columns so you put first one then the other into Geographical Coordinates when converting.
• 3. Manchester libraries: this file is a CSV as published in the Manchester City Council website. It's missing a column with POI categories (a required field for the AGT), so you have to add it yourself; you simply drag "Custom text" over to "POI categories" and then manually type in "libraries".
• 4. Sportcentres in Ghent: this is also a CSV from the Ghent open data hub. It has not only latitude and longitude (but we learned that with n. 2) but also street names and street numbers under separate colums. It will convert successfully if you only put "Straat" or even "Straat" followed by "nr" in the Address field, but the result is much better if you first put "Straat", then "Custom text" inserting a comma and space, and finally "nr".




Tutorial 3: Use the AGT to make an app

If you've got that far, this is the easiest part:

1. Please log in to the platform. You can create an account in a minute if you don't have one yet.
2. Use the Publish your Data menu to publish your converted file on the platform.
3. Then click on Create an app, and fill the form :
   1. select your desired city
   2. select the dataset you want to display ; note you can select multiple datasets, and switch cities in the process to get datasets from various cities
   3. select the 2 main colors for your app interface
   4. find a nice icon to represent your app
   5. name and describe the app...
4. Click on the submit button, and you're done ! It's that simple.

You'll certainly want to repeat the process a few times to try different datasets, combine datasets, or get back to the first 2 steps to adjust your raw or converted data to your needs.





Tutorial 4: Fork and customize a template

Once you've played with the Application Generation Tool, you might want to get a bit further and probably host the application on your own server. This is were the templates matter : they basically provide the same kind of applications as the AGT, but you will be able to download them, and put them where you want. Furthermore, templates are fully reusable, so you can tweak them to include your town or organization logo, change the styles, interface, etc.