IP Geolocation Views & Maps

IP Geolocation Views & Maps (IPGV&M) makes it easy to create Views-based mapping solutions using the map renderer of your choice (Google, OpenLayers or Leaflet) with any location storage module of your choice, e.g. Get Locations, Geofield, Geolocation Field or Location. This allows you to pick and mix and bring together modules that without IPGV&M are incompatible. For example, you can break away from the Google look to realise a Leaflet-based solution with animated clustering and lots of map canvases and markers to choose from without you having to migrate all your Location nodes to Geofield.

More importantly IPGV&M adds some features you won't find as conveniently packaged elsewhere. These include marker appearance differentiation based on field values or ranges, various centering options, marker tags and tool tips.

Finally IPGV&M provides a set of visitor location retrieval technologies, both IP and HTML5-based, so that you can track where past visits came from and where current visitors are located, superimposing their locations as differently colored markers on your maps.

IPGV&M displays your maps via any of the three main Javascript mapping APIs. Just pick the one you like best for your solution. Our choice for most use-cases is Leaflet, but Google and OpenLayers are great too:
o Google API v3 (included, no further modules required)
o Openlayers API (requires OpenLayers module)
o Leaflet API (requires Leaflet module).

OpenLayers users: if you want to employ this module with the very latest version of OpenLayers, install "IP Geolocation Views and Maps" 7.x-1.x-dev.

For location storage IPGV&M accepts any of the following well-established methods. Pick your favourite:
o latitude and longitude as simple text fields on your node or user content types
o Get Locations module
o Geofield module
o Geolocation Field module
o Location module
o Commerce module (first screenshot)

The nice thing is that you can combine any of the above location storage methods with any of the three Javascript mapping APIs to render your preferred style of maps. And you can change to a different combination at any time.

Using Varnish? IP GV&M works nicely with Session Cache API for an accelerated web browsing experience. Read more here.

You may use code snippets to slip a user's HTML5 location to other modules to create targeted ads and announcements, local weather forecast, country-dependent pricing or to map nearby fellow visitors. In fact, IPGV&M contains the tools you need to enhance your website with location based services, as employed by mobile apps like foursquare, Blendr, Neer and Yelp.

1) View and maps

• You can display almost any view as a map. In the Views UI, under Format you will find that in addition to Table, Grid etc, there are new options: Map (Google, via IP Geolocation), Map (Leaflet, via IP Geolocation) (requires the Leaflet module) and Map (OpenLayers, via IP Geolocation) (requires OpenLayers). Tick one of those and your page, block or attachment display renders as a map!
• If in addition to latitude and longitude your view also outputs some other fields, then these will pop up in each marker balloon when the marker is clicked.
• When configuring the map view you'll be invited to optionally select a differentiator (second screenshot). Pick any field you wish to color-code the location markers by their corresponding field values. This way you can have restaurants in red, museums in blue etc... Or hotels color-coded by their price ranges...
• You can add your own fancy markers too! Download from, say http://mapicons.nicolasmollet.com, and just drop them in your nominated directory and they'll be available for selection.

OpenLayers features more mapping options than Google Maps or Leaflet. So OpenLayers is a bit more laborious to configure than the other two. However, OpenLayers is easy to use when you've configured it once. See the "OpenLayers Tips" section of the README included with the IPGV&M package download. We love Leaflet and its light-weight companion modules Leaflet MarkerCluster (third screenshot) and Leaflet More Maps.

2) Visitor location retrieval

Location providers supported by this module include the specific hardware (desktop, tablet, phone...) your visitors use, which may employ GPS, WiFi and mobile cell towers. Nowadays the fine detail can be almost frightening, i.e. lat/long coordinates with an accuracy of 30 meters and postal addresses down to the street and street number. If you don't want to collect or expose this degree of detail, you can switch it off on the configuration page and have IPGV&M fall back on a less fine-grained service or API, as provided by Smart IP, GeoIP API or one you write yourself.
The process used is called reverse-geocoding. IPGV&M therefore adds to geocoding modules like Location, Geofield/Geocoder, Geolocation field or Get Locations, which are about giving users the facility to enter postal addresses or lat/long coordinates themselves and then mapping those.
IPGV&M is also different from most in that, if desired, it can collect locations of guests that visited your site from before you installed this module, going back all the way to the day you launched your site.
For present and future visitor geolocation information IPGV&M's built-in data collection techniques are hard to beat and may involve WiFi, GPS and mobile cell towers. For historic visitor data, IPGV&M supports existing tried-and-tested contributed modules to pull in IP-to-lat/long and IP-to-city/suburb/village data. The following modules are supported as lat/long data sources:

• Smart IP (its submodule Device Geolocation is not required)
• GeoIP API (note: the port of this module to D7 appears to be still in progress, but this dev version appears to work fine).
• any module that implements hook_get_ip_geolocation_alter($location) -- see the For programmers section further down this page

IPGV&M does not require you to load any libraries. You do not need to register for any API keys, except when you use Smart IP in combination with the IPinfoDB web service. The API key required on the Smart IP configuration page is free and is sent to you by return email after you've applied at http://ipinfodb.com/register.php. Alternatively you could use the file-based option of Smart IP or employ GeoIP API, which is also based on a file, downloadable from here: GeoLiteCity.dat.gz. The file is free and no key is required.
For reasons of reporting efficiency and flexibility via Views IPGV&M maintains its own small database of location information of past visitors to your site. It does not copy the entire Smart IP or GeoIP databases.

Features

So what's in the box? You get 4 ready-to-use-blocks, several canned Views and some programming goodies.

There's a block displaying a Google map with marked locations of your most recent visitors. Each marker when clicked reveals in a balloon that visitor's IP address, full postal address (including suburb, street and number), number of page visits and date & time of the most recent visit. But nicer still is the canned View for any of the many Leaflet maps available, which features clustering and animation to attractively and clearly deal with maps containing thousands of location markers. You can see both maps live in action here.

View fields that do not have their Excluded box ticked will go in the marker balloons (when clicked), formatted just as they would have been in a standard view.

For those using the Commerce module a ready-to-use Order Locations map is provided (see screen shot). For each order placed at your store it outputs a marker on the map with its location details retrieved by IPGV&M. The view comes with filters to zoom in on country, time frame and order status. Each order location marker, when clicked, reveals in a text balloon details of the order, e.g number, date placed and order status as well as street address.

A global address lookup block: type an IP address and it will echo the closest street address information it can find. Bottom of this page.

Use the "Refine location" block to display the visitor's current reverse-geocoded address and allow them to tweak it to specify exactly where they are. Requires Geocoder.

There's also a number of variations of a block rendering a Map centered on visitor's current location. Three of them (one each for Google, Leaflet and OpenLayers) are based on dummy views and are customisable in terms of the marker color. The fourth block is a Google map not requiring Views. When clicked, the position marker of this Google map not only gives you detailed address information, but also a measure of the accuracy of the pinpointed location. Note: maps may be approximate or show up blank map when the visitor declines sharing their location when prompted by their browser or are using an old (IE) browser.

For sorting, reporting and exporting purposes: a couple of configurable views, Visitor Log and Visitor Log (lite), displaying time-ordered lists of locations from which your site was visited; each location has address information, a small map (if desired), page visit counts and first and last visits; naturally, these being views you may add, remove and rearrange columns as you wish. The Visitor Log report requires Views PHP.

Finally for programmers: an API to retrieve and respond to lat/long and address information and to generate maps. Below are some of the functions available. See ip_geoloc/ip_geoloc_api.inc for details.

function ip_geoloc_output_map_current_location($div_id, $map_opts...)
function ip_geoloc_output_map_multi_locations($locations, $div_id, $map_opts....)
function ip_geoloc_distance($location, $ref_location='current visitor');
function hook_ip_geoloc_marker_locations_alter(&$locations, $view);

Further ideas for interacting with visitor locations can be found in the For programmers section below.

Installation and configuration

See the README included in the package download.

Works well with

• Leaflet Mapbox: create your own MapBox "canvas", enter your MapBox map id and then use IPGV&M as before.
• EntityFieldQuery Views backend

Further reading and viewing

• DrupalCon Sydney presentation (YouTube). Also available here.
• Introduction to Geocoder
• Basic Dealer Locator, User Locator, Store Locator proximity search
• Comparison of mapping modules
• Has mobile mapping evolved?
• Done in 60 seconds: LBS example using IP Geolocation: map of buyer locations
• Done in 60 seconds: LBS example using IP Geolocation: traveller's blog

Geolocation technologies used

IPGV&M uses up to 4 methods to bring geolocation information to your screen. The first is the W3C Geolocation API. On desktops and laptops, the W3C API works on all major browsers, except IE before version 9. On mobile devices, it works on Android and iPhone. If the browser/device doesn't support the W3C API, IPGV&M will try s a number of device-specific API's, e.g. for Palm, Nokia and Blackberry (see supported platforms). Check support for your device and browser here. If a message with lat/lon coordinates pops up, you can expect IPGV&M to produce accurate address information for all visitors using that device and browser. If you get "Functionality not available", you are probably using IE6/7/8 (read this). IPGV&M will still be able to return address information though, as it falls back on Smart IP or GeoIP API, but the information returned is likely to be less detailed.

If retrieval of the lat/long coordinates via one of the above methods was successful IPGV&M then employs the client-side version of the Google Maps geocoding library v3 to reverse-geocode the lat/long into address information. The Google reverse-geocoding function returns more details than most. For example it usually includes street (route) and street number, postal code, locality (suburb) and administrative area level 1 (often corresponding to state). Should the Google API for whatever reason return an error, then IPGV&M employs Smart IP or GeoIP to execute an alternative, less detailed, postal address lookup based on IP address.

FAQs

Q: So how is the visitor map different from Google Analytics?
A: You can't seamlessly integrate GA into a Drupal web page. You can't use GA in Views or blocks. You'd also have to expose the login box and share the password in order for other users to view GA's location map. GA locates your visitors only down to city accuracy, while IPGV&M goes down to street address. GA updates come once every 24 hours whereas IPGV&M refreshes instantly. GA doesn't make the current visitor's location details available for you via ip_geoloc_get_visitor_location(). So you cannot use the visitor's location in code snippets.

Q: Why are my visitors prompted to confirm sharing of their location?
A: The prompt comes not from the module but from the browser via its W3C Geolocation interface. W3C states that every manufacturer implementing the interface MUST prompt the user and request permission whether they are ok with their lat,long location being sent to the server.
You can stop the IPGV&M module from asking the browser to use its accurate WiFi-based or GPS-based (i.e mobile phone) locater algorithms by unticking the box Employ the Google Maps API to reverse-geocode lat/long coordinates to street addresses, which is on the page Configuration >> IP Geolocation Views and Maps. With the box unticked, IPGV&M will no longer ask for lat/long to determine the browser location and instead use the far less accurate position location method based on IP address. This IP lookup will employ either the Smart IP or GeoIP API modules, depending on which one you have installed.

Q: Upon first visit, the visitor map seems to first show my service provider's location. It is not until I refresh the page that I get my actual location.
A: The process of acquiring your global position followed by the reverse-geocoding to a street address as displayed in the marker balloon, is initiated upon first click, but may take a few seconds to complete. Therefore to see the final results of this process you need to refresh the page.

Q: With some visitors I don't seem to get the location accuracy I was hoping for; what could be the reason for that?
A: Several. When prompted by their browser, the visitor may have declined to share their location as retrieved through WiFi, GPS etc. In this case IPGV&M falls back on an address lookup based on IP, which may return the location of the visitor's internet provider, rather than the visitor themselves. The fallback is also used when the location provider times out, is not available on the device used, or when the visitor is a crawler, which is usually not a real browser and may not have javascript enabled.

Q: How can I show in the marker balloon the distance to the vistior's current location?
A: If your view is based on the Location module, then add to the view the field "Location: Distance/Proximity". In its Settings panel, under Origin select "Use PHP code to determine latitude/longitude" and enter the following code:

Note 1: be aware that when testing this on http://localhost with HTML5-based geolocation switched off, you'll get a notice as there won't be any location data on the db for the IP address "localhost". With HTML5 location retrieval on, you should be fine, though.
Note 2: Geofield 7.x-2.x also offers a proximity field, but at the time of writing this field had to be a fixed reference point, not the visitor's moving position. Similarly, the Geolocation Proximity module adds a field to views based on Geolocation fields. It too has to be fixed. See #1661688: Option to enter PHP code snippet for lat/long.

Q: Which modules do you recommend to store street addresses that have their lat/long automatically geocoded for use in maps?
The trio of Address Field, Geofield and Geocoder is easy to configure and works well. It also allows multiple addresses and their automatically generated lat/long pairs being attached to the same node or user. To map them, make sure that in the View, the AddressField field has "Display all values in the same row" unticked, while the Geofield (and all other fields) have that box ticked.
The Location module also supports multiple locations per node.

Q: Can I display a map of the locations of authenticated users that recently logged on, updating their map positions as they move about? Can the map be centered on the user that last logged in?
A: Yes.

Q: Where can I find out more about the location retrieval calls initiated from my server, the time they took to execute and any errors that may have occurred?
A: Check the Reports >> Recent log messages page for details or tick the box Detail execution progress with status messages at the bottom of the Configuration >> IP Geolocation Views and Maps page, under "Advanced options".

Q: For debugging purposes, can I display in a block the current user's session location data?
A: Yes. First make sure that you have the core module PHP filter enabled. Then go Structure >> Blocks >> Add block. Set Text format to "PHP code". For something half readable enter in the block body something like this:

Note that, in order to see any meaningful session data when running on a local server (127.0.0.1), you must be connected to the internet and have ticked at Configuration >> IP Geolocation Views and Maps the data collection option Employ the Google Maps API to reverse-geocode lat/long coordinates to street addresses. When debugging it is also recommended to activate on the same page the advanced option Detail execution progress with status messages.

Some suspected web crawlers

You may find that the following are great fans of your web site, visiting it repeatedly ;-)

• "Mountain View, CA 94043, USA" (Google, IPs 66.249.68.*, 66.249.69.* etc)
• "Sunnyvale, CA 94089, USA" (Yahoo!, IPs 67.195.*.*)
• "Dongcheng, Beijing, China" (IPs 123.125.71.*, 180.76.5.*)

See also http://whois.domaintools.com

For programmers

IPGV&M stores location data for the current visitor in their session and makes it available via ip_geoloc_get_visitor_location(). So you can display content conditionally on the country or city that your users are visiting from. For instance you can restrict visibility of a block containing an ad or a news flash relevant only to a particular city by entering this little snippet in the Visibility settings of the block, under "Pages on which this PHP code returns TRUE":

By taking advantage of existing API's or by writing simple plugins for modules like Rules, Context (and potentially Context PHP) you should be able to add location-based conditions and (re)actions to your site. These would allow you to do things like:

• If the visitor is from the UK then alter price fields to show pounds rather than euros.
• If the visitor is located within 5 km of some reference location (as entered on a node or block), then show this ad, or pop up this message etc.
• Show a map centred around the visitor's current location showing other visitors in the area
• Add, remove or alter locations as returned by the View before they're being mapped, by implementing hook_ip_geoloc_marker_locations_alter().

Contact the maintainer if you wish to pursue any of the above and are happy to share the code with the community.
Finally, you may also hook your own gelocation data provider into IPGV&M. Details are in the README.

Google restrictions

The following was taken from http://code.google.com/apis/maps/documentation/geocoding. Note that this applies per (server) IP address, so will not be an issue for present or future visitors to your site, as the relevant calls are made via the client, each of which will have a different IP address. It may be something to be aware of when batch-converting historic IP addresses to postal addresses. Use batches smaller than 2500 per day.

Use of the Google Geocoding API is subject to a query limit of 2500 geolocation requests per day. (Users of Google Maps API Premier may perform up to 100,000 requests per day.) This limit is enforced to prevent abuse and/or repurposing of the Geocoding API, and this limit may be changed in the future without notice. Additionally, we enforce a request rate limit to prevent abuse of the service. If you exceed the 24-hour limit or otherwise abuse the service, the Geocoding API may stop working for you temporarily. If you continue to exceed this limit, your access to the Geocoding API may be blocked.
For complete details on allowed usage, consult the Maps API Terms of Service License Restrictions

Development sponsored by flink, the Drupal experts collective.

Downloads