Extension:Maps

Note: the documentation has not yet been updated for version 0.4.

Description
Maps is a MediaWiki extension that provides the ability to display coordinate data on maps and allows users to geocode addresses.

Due to it's unique structure, it allows you to use multiple mapping services to display your coordinates. These include Google Maps, Yahoo! Maps, OpenLayers, and also allow you to display maps with Google Earth, OpenStreetMaps, Bing maps and others. Modifying the mapping service of a map is as easy as changing a single parameter!

Semantic Maps is an extension built on top of maps, and adds semantic capabilities to it. When using Semantic MediaWiki, it is highly recommended to use Semantic Maps together with maps, since it will make coordinate insertion even easier. Examples of how to use Maps can be found here.

Both Maps and Semantic Maps are based on Semantic Google Maps and Semantic Layers, and are meant to replace those extensions. Maps contains all functionality of Google Geocoder, and so also replaces this extension.

Download

 * Maps0.3.4.zip 298.54 KB

You can find older version in the legacy downloads section of the legacy page.

Subversion downloads
You can also download the code directly via SVN from the MediaWiki source code repository, at http://svn.wikimedia.org/svnroot/mediawiki/tags/extensions/Maps/REL_0_3_4/. From a command line, you can call the following:

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/tags/extensions/Maps/REL_0_3_4/

To get the latest changes, you can download the code directly from the trunk. Note that this is discouraged when stability is a big concern.

Package downloads
Maps and Semantic Maps


 * MapsAndSemanticMaps0.3.4.zip 300.85 KB

Semantic Bundle

Installation
Once you have downloaded the code, place the 'Maps' directory within your MediaWiki 'extensions' directory. Then add the following code to your LocalSettings.php file after the line that installs Semantic MediaWiki:

For using Google Maps or Yahoo! Maps, you must enter their API keys. You need to add them in LocalSettings.php, after the inclusion of Maps.

If you don't already have them, you can obtain them at the Google Maps API page and Yahoo Maps API page. Note that the Google Maps API key is required for both displaying maps AND for geocoding (and therefore also required when you use display_address with a Yahoo! Map). Also note that use of the Google Maps API is free only if your site is accessible to the public; otherwise it costs money - read the Google Maps terms of service for further details.

Once you have successfully installed Maps, please add your wiki to the Sites that use Maps section.

Version
Maps is currently at version. It is still be considered beta, since some small issues might be present. However, it has been tested quite thoroughly, and should not cause any big problems.

Planned features
Curious about the upcoming features in the next release? The future work page contains on overview of the planned features, and the proposals that have been turned down.

Change log
This list only contains the versions and their release dates. For a list of all changes made, view the change log section of the legacy page.


 * Version 0.4 (2009-11-03)


 * Version 0.3 (2009-08-14)
 * Version 0.3.1 (2009-08-18)
 * Version 0.3.2 (2009-08-18)
 * Version 0.3.3 (2009-08-25)
 * Version 0.3.4 (2009-09-12)


 * Version 0.2 (2009-07-29)
 * Version 0.2.1 (2009-07-30)
 * Version 0.2.2 (2009-08-01)


 * Version 0.1 (2009-07-20)

Languages supported
Maps has support for English, Arabic, Belarusian, Breton, Bosnian, Catalan, German, Lower Sorbian, French, Galician, Swiss German, Hebrew, Croatian, Upper Sorbian, Hungarian, Indonesian, Japanese, Ripoarisch, Luxembourgish, Dutch, Occitan, Polish, Piedmontese, Brazilian Portuguese, Romanian, Tarandíne, Russian, Slovak, Vietnamese and others.

Display a single point


You can display a map with a marker on it with the #display_point parser function. The following code will display a marker on the default map type (Google Maps), at the provided coordinates. Examples.

The above example demonstrates the floating-point coordinate notation. You can also use the DMS notation, as shown below. All other examples in this article will use the floating-point notation.

Note that the coordinates parameter is the default parameter for #display_point. This means that the name can be omitted, like shown below.

Geocoding
To make it easier to display a marker on an address, geocoding functionality is included in Maps. This functionality is based on the Google Geocoder extension, which you will need to un-install before using Maps. You can geocode an address with the #geocode parser function. The underneath code will return the coordinates of Moscow.

This can be easily nested in the #display_point parser function, like demonstrated below. Examples.

To avoid this nesting, another parser function, #display_address, is also available. This parser function is completely identical to #display_point, except for the parameter address, which replaces coordinates, and automatically does the geocoding for you. This code is completely synonymous to the previous example. Examples.

Note that the address parameter is the default parameter for #display_address. This means that the name can be omitted, like shown below.

Geocoding service
Maps allows you to use multiple geocoding services. Both the available geocoding services as the default geocoding service are settings, and can be modified. If you don't want to use the default service, you can specify it in the parser function.

The #geocode parser function accepts a second argument, like shown below:

display_address also accepts this argument, but in contradiction to the one in #geocode, it's named: geoservice.

In some cases, the default geocoding service will be overridden with another value.
 * In a display_address Google Maps map: google will be used as the default
 * In a display_address Yahoo! Maps map: yahoo will be used as the default

This only overrides the default geocoding service that's used when no service is provided in the parser function.

Legal warning
Both the Google and Yahoo! geocoding services have a licence that prohibits their use for anything that is not directly related to their associated mapping services, unless you have written permission. You are encouraged to read the service's licences (Google, Yahoo!) before using them.

The underneath examples are in violation of the relevant licences in most cases:

Map services


Maps provides multiple mapping services. The map service for a certain map can be set with the  parameter. When the service is omitted, the default service will be used. The underneath list contains the available mapping services.

When no service is provided, the default service will be used.

Map properties


All map-display parser functions in Maps (display_point, display_points, display_address & display_addresses) accept a number of map properties (also referred to as parameters). These properties can be altered to change the appearance and usage of the resulting map. Each property has a specific usage, as listed in the underneath table.

Each display_ parser function only has one required parameter, either coordinates or address. To make life easier for you, it's not even required to provide the names of these parameters (see example below). All other parameters are optional, and most of them have a default value that can be configured in the settings file.

Example with the omit-able address name.

Example in which the name has been omitted. This is synonymous to the above one.

Some of the properties have aliases. This means they can be set using multiple names. An example for this is the coords alias, which will have the exact same result as when using coordinates. All aliases are listed in the underneath table.

Example of a Yahoo! Map with multiple optional parameters.

Since each mapping service has it's own unique features, they also have properties specific to them. See the relevant sub page of this article for the list of a service's specific properties.

Display multiple points


You can display multiple points on one map by using the display_points and display_addresses parser functions. They work identical to display_point and display_address, respectively. The only differences are the coordinates and addresses parameters. Both accept a list of coordinates or addresses, in which each item is separated by a ';'. Underneath examples demonstrate the use of these parameters for both parser functions:

coordinates=55.7557860, 37.6176330; ; 1,1

addresses=Moscow, Russia; New York; London

Marker specific data
You can specify some marker specific parameters, which will allow you to have different po-pups and icons for different markers. These properties are added in the coordinates or addresses parameters, together with the coordinates.

There are 3 marker specific parameters. They are unnamed, meaning you notate them as value, not name=value, and therefore have a fixed order. Each parameter is separated by '~'. This is the correct order of the 3 parameters: coordinates or address, (optional) title, (optional) label, (optional) icon. Both title and label will use the value of their general, non marker specific, parameter, when it's set. This example demonstrate the parameters usage:

addresses=Moscow, Russia~Moscow~A city in Russia; New York~New York city; London~London~Capital of England~green-marker.png;Brussels


 * : The address is followed by a title (Moscow), and a label (A city in Russia), and will therefore display a marker with both values.
 * : This address only has a title parameter (New York city), and will not have any label, unless either  or   parameters are provided.
 * : This address has all 3 parameters, and will display a pop-up with it's own title, it's own text, and will have it's own marker (an image with the name green-marker.png).
 * : This address does not have any specific parameters, and therefore will use the default marker icon, and won't display any pop-up, unless either  or   parameters are provided.

This is a stripped down example:

addresses=Address~Title~Label~Icon

Settings
Maps allows you to configure a variety of settings, and so affect how the extension works. All settings are located in Maps_Settings.php, in the root of the extension. You can modify a setting by copying it's code and placing it with the adapted value in LocalSettings.php, after the inclusion of Maps. Here you have a list of the common settings (the ones that affect all mapping services). For the specific settings, see the map services. Note that the settings file is documented, and should provide you with sufficient information to understand the working of all settings.

Available mapping services
Array containing all the services that will be made available to the user. Currently Maps provides the following services: googlemaps, yahoomaps, openlayers.

Default:

Default mapping service
The default mapping service for each feature, which will be used when no valid service is provided by the user. This service needs to be enabled, if not, the first one from the available services will be taken. Note: The default service needs to be available for the feature you set it for, since it's used as a fall-back mechanism.

Default:

This list contains all available features, and their feature code, which should be used as name in the $egMapsDefaultServices array.
 * pf - parser functions - This default will be used for all display_ parser functions.
 * qp - query printer - This default will be used for all semantic queries.
 * fi - form input - This default will be used for all form input maps.

An additional fall-back value is present, that will be used in case no default is specified for a certain feature. This service needs to be enabled, if not, the first one from the available services will be taken.

Default:

Available mapping features
Array containing all the mapping features that will be made available to the user.

Available geocoding services
Array containing all the geocoding services that will be made available to the user. Maps 0.2 has support for 2 geocoding services: google and yahoo.

Default:

Default geocoding service
The default geocoding service, which will be used when no service is provided by the user. This service needs to be enabled, if not, the first one from the available geocoding services will be taken.

Default:

Default map coordinates
The default coordinates of the marker. This value will only be used when the user does not provide one.

Default:

Default map width
The default width of a map. These values will only be used when the user does not provide them.

Default:

Default map height
The default height of a map. These values will only be used when the user does not provide them.

Default:

Default map zoom
The default zoom of a map. This value will only be used when the user does not provide one. Each service has it's own zoom setting. Please refer to the mapping services for more info.

Extending Maps
Maps has been designed to be very extendible. Due to it's modular structure, it's possible to add a completely new mapping service without changing a thing in any of the core code, or even the extension's files. Adding a new mapping service has a whole list of advantages against creating your own extension to handle that service. Some of the most noteworthy are listed below.


 * Less work to create: The Maps code already handles the common features, and only requires mapping service specific code, sparing you the need to write code to handle problems other people have solved before. As a developer, you will also be able to take advantages of improvements made to Maps itself, without having to implement them over and over again in your own code.


 * Follows convention: By using the central Maps code, your not creating similar, but different code, which makes it easier for people to discover, locate and fix problems, and to add new functionality. This also makes usage for end user a lot easier, since the wiki code will always be similar to the extend possible.


 * Ease of installation: Installing one extension (possibly bundled with 3rd party mapping service implementations) is far easier then installing half a dozen for an end user. It also solves issues with incompatibility between multiple mapping services, which can cause extensions to break.


 * More publicity and usage: Since Maps is the only mapping extension for MediaWiki that handles a true mapping service independent platform, and cause of that provides multiple mapping services and a variety of both common and specific features, users are far more likely to choose Maps instead of multiple individual extensions.

How to extend Maps
You can learn how to create your own extension for Maps by looking at the source code and doing some experimenting, or you can read the manual, that goes through all the required steps.

Bugs, patches and new features
If you found some bug and fixed it, please create a patch by going to the "Maps" directory, and typing:

svn diff >descriptivename.patch

Then add the patch to the bugs section of the future work page. Bug reports should also be added here. You can also send them to Jeroen De Dauw, jeroendedauw -at- gmail.com, and Yaron Koren, at yaron57 -at- gmail.com.

If you created new functionality for Maps, please contact one of the developers to discuss the best way to integrate it.

Feature requests
Feel free to add feature requests to the new proposals section of the future work page.

Translating
Translation of Maps is done through translatewiki.net. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on translatewiki.net, then request permission from the administrators to translate a certain language or languages on this page (this is a very simple process). Once you have permission for a given language, you can log in and add or edit whatever messages you want to in that language.

Getting support
If you have any Maps related questions, you can add them to the Talk page. You can alternatively also place any questions on the Semantic MediaWiki mailing list, semediawiki-user. If possible, add "[Maps]" at the beginning of the subject line, to clarify the subject matter. Please contact the extensions authors only directly for urgent matters. Placing your questions on the talk page will create useful references for other people with similar problems.

Sites that use Maps
Are you using Maps? Then be sure to add your wiki to the top of this list, and feel free to link your favourite Maps-using articles!


 * Ticopedia.de
 * Bougna Citizen Information
 * Children are Welcome
 * ShelterCrisis
 * B3OK
 * Civic Studio "On the River" project
 * Discourse DB
 * Food Finds
 * GingerWiki
 * Semantic MediaWiki community wiki
 * Mikomos
 * BN's demo wiki
 * syn2cat Hackerspace