Geocoding

Documentation

Geocoding Topics

What is the expected file format for the geocoder? What do the geocoder inputs mean? What Google API components are not implemented in the RSG geocoder? How do I use the geocoder API in a survey?

What is the expected file format for the geocoder?

Currently, the application only supports .CSV files. The application is expecting headers in the first line, one of them being 'address'. The application will then use the address field for geocoding.

Example file

id	address	lorem	ipsum
1	123 Broadway	...	...
2	456 Center Street	...	...
3	300 North 500 West	...	...

What do the geocoder inputs mean?

The geocoder is using inputs provided by Google, except for the Project field, which is required by RSG. All Google documentation can be found here .

Project - The Project field will be used for auditing and reporting once the reporting module is complete.

Bounds - From the Google documentation, "The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder." See Viewport Biasing from the Google API docs.

Region - From the Google documentation, "The region code, specified as a ccTLD ("top-level domain") two-character value. This parameter will only influence, not fully restrict, results from the geocoder." See Region Biasing from the Google API docs.

Components - From the Google documentation, "The component filters, separated by a pipe (|). Each component filter consists of a component:value pair and will fully restrict the results from the geocoder." See Component Filtering from the Google API docs.

Geocoder inputs

What Google API components are not implemented in the RSG geocoder?

Until needed, reverse geocoding with a lat/lng and specifiying a different language have not been included.

How do I use the geocoder API in a survey?

The following browsers are supported:

Chrome 3+
Firefox 3.5+
Opera 12+
Safari 4+
Internet Explorer 8+

Here is an example of how to use the API.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>API Example</title>
    <style>
      .map {
        position: absolute;
        top: 0;
        left: 0;
        bottom: 0;
        right: 0;
      }
    </style>
  </head>
  <body>
    <div class="map"></div>
    <script src="//ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"> </script>
    <script src="http://rsgmapportal.cloudapp.net/js/libs/rsgjs/1.0/rsg.min.js"> </script>
    <script>
      var map;

      function geocodeTest() {
        // model properties: 
        // address, 
        // bounds, 
        // region, 
        // components

        var model = {
          address: '41 N Rio Grande St., Salt Lake City, UT'
        };

        rsg.geocoding(model, {
          success: function (data) {
            try {
              if (data.status === 'OK') {
                var geometry = data.results[0].geometry,
                    marker = new google.maps.Marker({
                      position: new google.maps.LatLng(geometry.location.lat, geometry.location.lng),
                      map: map
                    });

                console.log(data);
              }
              else if (data.results.length === 0) {
                console.log('No results found.');
              }
              else {
                console.log(data.status);
              }
            }
            catch (ex) {
              console.log(ex.message);
            }
          },
          error: function (data) {
            console.log(data.alert.msg);
          }
        });
      }

      rsg.config('project-key', 'username');

      rsg.loadScript(function () {
        var element = $('.map').get(0),
            center = new google.maps.LatLng(40.767732473824125, -111.90398519592286);

        map = new google.maps.Map(element, {
          center: center,
          zoom: 16,
          mapTypeId: google.maps.MapTypeId.ROADMAP
        });

        geocodeTest();
      });
    </script>
  </body>
</html>

The API is dependent upon jQuery, you'll notice that it gets loaded first.

To use with IE 8 you will need to downgrade jQuery.

Replace this:

<script src="//ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"> </script>

With this:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"> </script>

rsg.config('project-key', 'username')

This is called to initialize and use the API, where you are passing it the project key (or project number, etc.) and providing it with a username.

rsg.loadScript(callback)

This is called to load the Google Maps API, along with an optional callback that can be executed after the script is loaded.

rsg.geocoding(model, { success: {...}, error: {...}})

This is called to make a geocoding request that is sent to the Google Geocoding REST API.