FortiusOne Geocoder

FortiusOne built the geocoder powering GeoCommons and GeoIQ appliances in order to provide users with an easy way to georeference their data from spreadsheets. Currently, the Geocoder works only in the United States, and in the future will be expanded to work globally. The GeoCoder is built in collaboration with the U.S. Federal Geospatial Data Committee (FGDC)

The FortiusOne Geocoder is open-source and available from our repository at http://github.com/geocommons/geocoder.

What is Geocoding?

Geocoding is the process of finding geographic coordinates from other geographic data, such as street addresses or ZIP codes.
The built in geocoder within Finder! makes it simple to retrieve longitude and latitude coordinates from your location based CSV files. The geocoding process has been fully integrated into the upload process, and will retrieve accurate coordinates based upon the location based values found in your CSV file.

Required Geographic Data for GeoCoding

There are many types of geographic data out there but the GeoCommons GeoCoder will only accept certain types of geographic data for GeoCoding purposes. By having these data types in your CSV, the GeoCoder will be able to take your uploaded data and assign latitude and longitude coordinates to the data for mapping purposes. Below are the accepted data types that will work in the GeoCoder.

What can the GeoCoder not GeoCode?

If your CSV does not have one of the above combinations you will receive an error during the upload process into Finder! Below are some unaccepted combinations that will cause an error:

As of now, it is important to realize that the GeoCoder is only able to GeoCode geographic locations that are located within the USA. Developments are in process to soon begin working on an international GeoCoder.
Also, make sure when GeoCoding, street addresses do not contain PO Box numbers. The GeoCoder is not able to GeoCode such locations and will give latitude and longitude coordinate results based on the postal code/ZIP code given in the CSV.

Preparing your CSV for GeoCoding: Single Field and Separated Fields

So how do you make a CSV with geographic data ready for GeoCoding? These tips can help you learn the correct methods when preparing a CSV for GeoCoding.

When formatting your CSV for upload, you can either breakdown your file into basic fields or you can place them together in a single field. Below is an example of a CSV that has been broken down into parts:

Please note that each row of your spreadsheet will represent one point location to the geocoder and eventually any maps created from your data.

As you can see above the address/city/state/country/ZIP code fields are separated into different columns. When the GeoCoder receives this file it will take the separated fields, recognize their geographic types, combine them appropriately, and then GeoCode for latitude and longitude results.

Your geographic data can also be combined into a single field. See the example below:

When combining the data into one address form, there are a few things to keep in mind to allow for the best possible GeoCoded results.
  1. Use commas to separate the different geographic fields
  2. Keep the fields consistent
    • Use same separators (commas) in all attribute entries
    • Use same geographic types in all attribute entries

By following these formatting guidelines, you will be able to successfully GeoCode your data in the GeoCommons GeoCoder.

Saving my Excel Spreadsheet as a CSV

Once you have properly formatted your spreadsheet you will want to save it as a CSV file. This can be done following these steps in Microsoft Excel:
  1. Select the Save As option from the Excel options dropdown.
  2. Choose the location you wish to save your file to.
  3. Title your dataset in the File Name: field.
  4. Select the Save as type: CSV (Comma Delimited) option from the drop down menu.
  5. Finally click the save button.

Please note that when saving a CSV file multiple sheets cannot be saved. After clicking the save button you will be prompted with this information. Please make sure that you do not have any important data on any sheets other than the one you wish to save.

Uploading your CSV into Finder!

Now that you have your file saved as a CSV, you can upload and GeoCode it through Finder!. Follow these steps in order to complete your upload:
  1. Start on the Finder! homepage.
  2. Scroll to the Upload a file from your computer: field.
  3. Select the Browse button. A new window will pop up allowing you to browse your computer for your saved CSV file. Please select the file and click the Open button.
  4. Click the Upload button.
  5. You will then be directed to Step 2, Locate, which appears below:

Step 2: Assigning Location

The next page is called the Locate Page and should look similar to this:

You will notice that you have the ability to edit the names of the attributes you have loaded up at this time. Simply click on the box and make any changes that you feel are necessary. They will automatically save when you hit continue to go onto step 3.

If you have formatted you geographic data to be joined together in one field then Step 2 may look like this:

On this page you will select a geographic format for at least one item on the list. You will notice that each Attribute represents one column heading from your CSV file. Finder! will automatically match up basic geographic formats with attributes with common titles. As you can see Finder! automatically matched the City attribute with the City Type of Data. Please review the current matches, if you wish to change any types of data simply select the edit button. A pop tab will expand and you will be presented with a number of options for types of data. The pop out window will look like this:

Standard attributes

As you can see you have two options: Standard and Geographic. Please use the standard options for all of your non geographic data. Your standard options are as follows:

Geographic Attributes

The Geographic option should be used on all of your geographical data. By selecting any of these options, you tell the geocoder to include this information in the geocoding process.

Step 3: Review your data

Once you have selected all of the proper Attribute file types you can continue with the upload process.

  1. Select the Save button.
  2. You will be taken to the Review screen.

  1. Please review your data to make sure that everything is correct. You have the option to expand the window to see the entire table by selecting the Expand View option.
  2. Two Columns of data will be added to your geocoded layer: Precision and Score
    • Precision – this label shows the level at which the data was geo coded to. Street level has the finest granularity. If the precision is at Zip, City, or State, the location was geo-coded to the centroid of that geography.
    • Score (Geo-confidence score) - An estimate of the probability that the latitude and longitude assigned by the Geocommons / GeoIQ geocoder to a place name correspond to the place the user intended. 0.0-1.0 scale, 0 zero being the least confidence, 1 being very confident.
  3. Select Continue when you are satisfied.

Identifying GeoCoder Errors

GeoCoding large CSV files may be challenging for the GeoCommons Geocoder. If you load a file that has thousands of entries you may see this error:

If you do come across this error try to reupload your CSV again. If it fails a second time try breaking your original CSV into smaller parts and upload the smaller parts separately.

The GeoCoder is not always able to GeoCode every geographic attribute that you upload into Finder. This means that the GeoCoder was unable to find a match for the data that you entered.

The GeoCoder is able to report to you the number of attribute records that were GeoCoded and those that were not. Your overall match and unmatched totals will be recorded at the top of the page.

You may find yourself receiving errors if you do not assign you attributes the proper data format type in step 2 of the GeoCoding process. In the picture below the attribute of city was accidentally assigned as a decimal number by me, the user.

The GeoCoder is able to identify the problem and show why the GeoCoding process has failed. By hovering your mouse over the red boxes you are able to view a text box that explains why an error occurred during the GeoCoding process. After identifying the mistakes, you can go back and correct them by hitting the ‘Start Over’ button or the ‘Back’ button. The ‘Back’ button will take you back to step 2 and the ‘Start Over’ button will take you to the Finder! homepage where you can re-upload your CSV file.

If you have received errors or a large number of you entries have not been GeoCoded, we strongly recommend looking back over your CSV that you have uploaded. Check to make sure that the data is formatted cleanly. Also check to see that the data is consistent. Refer back to the section of this manual entitled, Preparing your CSV for GeoCoding: Single Field and Separated Fields, for more help in formatting your CSVs correctly.

Step 4: Describe your data

You will now be directed to the Describe window. Shown below:
  1. Please fill out all of the description fields, which include title, tags, contact information, etc. For more information regarding the proper description procedures, please see the description section of this manual.

    The 'How was this data processed?' Section of the description window is very important for letting other users know exactly how you gecoded your data. Please provide any details about your processing in the Processing Notes section as well as a link and name of the Geocoder you used.
  2. Click Save when you are finished describing your data.
    At this point your dataset is saved under your “My Layers” section. You now have the option to export, visualize and share your dataset.