Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A Javascript library to create and embedded map to find the latitude and longitude of a point, using the ModestMaps Javascript API.

branch: master
README.pod

NAME

iamheremap.js - create a map for tracking lat/lon using ModestMaps

SYNOPSIS

 <html>
        <head>
                <title>I Am Here Map</title>
                <script type="text/javascript" src="iamheremap.js"></script>

                <script>
 $(document).ready(function(){ 
        var args = {
                'modestmaps_provider' : 'CloudMade',
                'flickr_apikey' : 'YER_FLICKR_APIKEY',
                'cloudmade_apikey' : 'YER_CLOUDMADE_APIKEY',
                'map_style' : 999,
                'enable_logging' : true,
        };

        window.map = new info.aaronland.iamhere.Map('iamheremap', args);
 });
                </script>
        </head>
        <body style="margin:0;">
                <div id="iamheremap"></div>
        </body>
 </html>

DESCRIPTION

I Am Here Map is a Javascript library to create and embedded map to find the latitude and longitude of a point, using the ModestMaps Javascript API.

It also supports geocoding, reverse-geocoding and automagic client positioning using a variety of geolocation providers as well as the ability to display shape contours for locations that have been reverse-geocoded.

It is heavily indebted to Simon Willison's original www.getlatlon.com website.

EXAMPLE

http://www.aaronland.info/iamhere/

OBJECT METHODS

new info.aaronland.iamhere.Map(args)

  • modestmaps_provider (required)

    Valid providers are :

    • CloudMade

      Use map tiles provided by CloudMade. You will need a valid CloudMade API key.

      See also: http://maps.cloudmade.com/

    • A MapProvider-derived class (instantiation) of your own

      You may also specify a ModestMaps MapProvider-derived class of your own.

      For example, to if you wanted to use OpenStreetMaps tiles:

       info.aaronland.iamhere.OpenStreetMapsProvider = function() {
              com.modestmaps.MapProvider.call(this, function(coordinate) {
                      var img = coordinate.zoom.toFixed(0) +'/'+ coordinate.column.toFixed(0) +'/'+ coordinate.row.toFixed(0) + '.png';
                      return 'http://tile.openstreetmap.org/' + img;
              });
       };
      
       com.modestmaps.extend(info.aaronland.iamhere.OpenStreetMapsProvider, com.modestmaps.MapProvider);
      
       var osm = new info.aaronland.iamhere.OpenStreetMapsProvider();
      
       var args = {
              'modestmaps_provider' : osm,
              // all your other args here
       };
      
       window.map = new info.aaronland.iamhere.Map('map', args);
  • cloudmade_apikey

    A valid CloudMade API key. Required if your modestmaps_provider is "CloudMade".

    You can register for a CloudMade API at http://developer.cloudmade.com

  • map_style

    A map style specific to the tile provider.

    Required if your modestmaps_provider is "CloudMade" (use '999' for the spooky).

  • flickr_apikey

    A valid Flickr API key.

    Required for things like reverse geocoding and displaying location contours.

    You can register for a Flickr API key at http://www.flickr.com/services/api/keys/apply/

  • latitude

    The latitude where the map should be displayed on load.

    The default is 0

  • longitude

    The longitude where the map should be displayed on load.

    The default is 0

  • zoom

    The zoom level that the map should load with.

    The default is 2

  • map_height

    Default is 400.

  • map_width

    Default is the width of the browser window.

  • auto_display_shapefiles

    Automatically load and display Flickr shapefiles for a location. Obviously, this requires that you pass a valid Flickr API key and that a point be successfully reverse geocoded.

    Default is false.

  • disable_query_args

    I Am Here maps are set up to allow a limited number of config options to be read from query arguments, passed either as proper query arguments or in the hash component of the URL. These options take a higher precedence than those passed to the object constructor.

    This flag will disable this feature. If true, this has the side-effect of disabling auto-generated (and updating) permalinks since there's not really any point, is there?

    Default is false.

  • max_decimal_points

    If not-null, trim the number of decimal points by this number when displaying latitudes and longitudes.

  • refresh_title

    If true, refresh the page title with the current latitude and longitude (and place name if reverse geocoding was successful).

    Default is false.

  • enable_logging

    Write events and errors to console.log

PERMALINKS AND QUERY ARGUMENTS

Unless otherwise disabled, the following parameters may be passed as "starting" arguments. They will also be automatically updated in the hash (#) component of the URL whenever the map changes position.

  • latitude

    Assign the latitude of the map's current center point.

  • longitude

    Assign the longitude of the map's current center point.

  • zoom

    Assign the map's current zoom level.

  • style

    Shorthand for the 'map_style' argument, and included only if present in the original URL.

  • shapefiles

    Shorthand for the 'auto_display_shapefiles' argument, and included only if present in the original URL.

If you pass a URL containing a real and proper query fragment it will be rewritten (and redirected) to the same URL with the arguments passed in the hash component. This is mostly to make "pretty" URLs even if they may not be technically "correct".

GEOCODING

Geocoding addresses is performed using either the Google Maps geocoding (v3) API or the Flickr API, assuming the requisite libraries have been loaded and API keys defined.

The order of precedence for geocoding is:

  • Google Maps API

    Version 3, and higher.

  • Flickr API

    Using the flickr.places.find API method, which does not do street-level geocoding.

REVERSE GEOCODING

Reverse geocoding of points is performed using the Flickr API, assuming you've included a valid Flickr API key.

POSITIONING

Positioning (or geolocating) of the current user is attempted using a variety of providers assuming the requisite libraries have been loaded and/or valid API keys have been defined.

The order of precedence for positioning is:

  • Loki/Skyhook API

    Loki is first on the assumption that if you've passed a Loki API key then it's probably what you want to use; this may not hold true if you're using a browser/device with a built-in GPS unit but one step at a time.

  • Geode API

    Firefox only.

  • Google Gears Geolocation API

    Requires the Google Gears plugin/extension.

  • Google ClientLocation API

    IP lookups.

The actual mechanics of the positioning logic are handled by the js-geolocation library.

KNOWN-KNOWNS

  • This has only been tested in Firefox and Safari.

    It should work in IE, but who knows...

  • The use (and size) of JQuery is probably overkill.

    All things being equal it will probably be replaced with plain-vanilla native DOM calls in time.

  • The size and position of map (and the crosshairs) are fixed.

    They still don't update correctly when the window is resized.

  • I haven't figured out packing/minifying for this yet.

    It's probably just a missing cluebat but so far when I try I end up with weird Javascript errors.

    * This uses a modified version of the 'mapcontrols-raphael.js' library.

    I haven't gotten around to writing a proper patch yet against the ModestMap codebase yet..

BUGS?

Probably. Please to be gentle.

AUTHOR

Aaron Straup Cope

LICENSE

Copyright (c) 2009 Aaron Straup Cope

This is free software. You may redistribute it and/or modify it under the same terms as Perl Artistic License.

http://en.wikipedia.org/wiki/Artistic_License

SEE ALSO

http://www.aaronland.info/weblog/2009/06/01/bubblegum/#iamhere

http://www.modestmaps.com/

http://developer.cloudmade.com/

http://raphaeljs.com/

http://www.getlatlon.com/

http://github.com/straup/js-iamheremap/

http://github.com/straup/js-flickr-api/

http://github.com/straup/js-geolocation/

Something went wrong with that request. Please try again.