Extension:Maps

From MediaWiki.org

Manual on MediaWiki Extensions
List of MediaWiki Extensions

Maps Release status: beta
Implementation	Parser functions
Description	Allows users to display maps and coordinate data using multiple mapping services.
Author(s)	Jeroen De Dauw, Yaron Koren, Robert Buzink, Matt Williamson and Sergey Chernyshev
Last Version	0.4.2 (2009-11-15)
MediaWiki	1.9.* or higher
License	GPL
Download	Maps0.4.2.zip
Hooks used LanguageGetMagic AdminLinks
check usage (experimental)

[edit] 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.

Maps:

Introduction • Download • Installation • Usage • Version history • Future work • Contributing • Extending Maps • Semantic Maps

Language:

English  • Nederlands

[edit] Setup

[edit] Download

• Maps0.4.2.zip 329.7 KB
• Maps0.4.2.7z 216.11 KB

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

[edit] 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_4_2/. From a command line, you can call the following:

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

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.

[edit] Package downloads

Maps and Semantic Maps

• MapsAndSemanticMaps0.4.2.zip 370.35 KB
• MapsAndSemanticMaps0.4.2.7z 228.66 KB

Semantic Bundle

[edit] 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:

# Maps
require_once( "$IP/extensions/Maps/Maps.php" );

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.

# API keys configuration
$egGoogleMapsKey = ""; # Your Google Maps API key. Required for displaying Google Maps, and using the Google Geocoder services.
$egYahooMapsKey = ""; # Your Yahoo! Maps API key. Required for displaying Yahoo! 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.

[edit] Version

Maps is currently at version 0.4.2. 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.

[edit] 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.

[edit] 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.4.1 (2009-11-10)
  • Version 0.4.2 (2009-11-15)

• 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)

[edit] Languages supported

Maps has support for English, Afrikaans, Arabic, Belarusian, Breton, Bosnian, Catalan, German, Lower Sorbian, Greek, Spanish, Basque, Finnish, French, Friulian, Galician, Swiss German, Hebrew, Croatian, Upper Sorbian, Hungarian, Interlingua, Indonesian, Japanese, Ripoarisch, Luxembourgish, Macedonian, Dutch, Occitan, Polish, Piedmontese, Brazilian Portuguese, Romanian, Tarandíne, Russian, Slovak, Swedish, Thai, Vietnamese and others.

[edit] Usage

[edit] Coordinates

Maps supports several coordinate notations, which you can use to display points, set the centre of maps, and more:

• Floats: 55.7557860, 37.6176330
• DMS: 55°45′06″N 37°37′04″E
• DD: 55.7557860°, 37.6176330° or 55.7557860° N, 37.6176330° E
• DM: 55°45.34716', 37°37.05798'

[edit] Geocoding

Since people work with addresses instead of coordinates, geocoding functionality is included in Maps. This means Maps will convert a human readable address to a set of coordinates. This functionality is based on the Google Geocoder extension, which, if installed, 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.

{{#geocode:Moscow, Russia}}

Result:

55.7557860, 37.6176330

In most cases, you will want to do something like displaying a map of New York, or indicating a couple of streets somewhere. Maps has build in support for those, and will automatically recognize addresses from coordinates, allowing automatic geocoding, without the need for the #geocode parser function. This behaviour is explained further in the relevant sections of the documentation.

[edit] 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:

{{#geocode:Moscow, Russia|yahoo}}

In some cases, the default geocoding service will be overridden with another value.

• In a display_map/display_point(s) Google Maps map: google will be used as the default
• In a display_map/display_point(s) 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.

[edit] 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:

{{
#display_address:
Moscow, Russia
|service=google
|geoservice=yahoo
}}

{{
#display_point:
{{geocode:Moscow, Russia|google}}
|service=yahoo
}}

[edit] Displaying a map

• Watch display_map screencast (1.27MB)

Maps enables you to display a map by using the #display_map parser function. Such a map will centre itself around a provided location, which can be a set of coordinates, or an address. In the later case, it will be automatically geocoded. You do not need to specify if the provided value is a set of coordinates or an address, this will be automatically determined.

The following code will result in a map of moscow.

{{#display_map: Moscow}}

Or

{{#display_map: 55°45′06″N 37°37′04″E}}

The above examples demonstrate the use of addresses and DMS coordinates. You can also use the other supported coordinate notations.

You can further customize your map by adding additional map properties.

[edit] Displaying points

[edit] One point

Maps indicating Moscow on a Google Earth map.

You can display a map with a marker on it with the #display_point or #display_points parser functions. By default, the map will centre itself around the provided point, which can be a set of coordinates, or an address. In the later case, it will be automatically geocoded. You do not need to specify if the provided value is a set of coordinates or an address, this will be automatically determined. The underneath code will result in a map on which the city centre of Moscow is indicated.

{{#display_point: Moscow}}

Or

{{#display_point: 55.7557860, 37.6176330}}

The above examples demonstrate the use of addresses and floating point coordinates. You can also use the other supported coordinate notations. Also note that there is no difference between the use of display_point and display_points. These functions are completely synonymous.

The usage of display_address has been deprecated since version 0.4. For backward compatibility, it is currently synonymous to display_point, but this will be removed at some point.

You can further customize your map by adding additional map properties.

[edit] Multiple points

An OpenLayers map with multiple markers on the OpenStreetMap cycle layer.

When you want to display multiple points on a Map, you can do this by adding them to a #display_point or #display_points parser function. Both accept a list of points, that can contain both coordinates and addresses, in which each item is separated by a ';'. Underneath example demonstrates how you can create a map with multiple points indicated:

{{#display_points:55°45′06″N 37°37′04″E; New York; 40.446195, -79.948862}}

The usage of display_addresses has been deprecated since version 0.4. For backward compatibility, it is currently synonymous to display_points, but this will be removed at some point.

You can further customize your map by adding additional map properties.

[edit] Point specific data

Maps allows you to specify point specific data. In other words, you can have different po-pups and icons for different markers.

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:

{{
#display_points:
Moscow, Russia~Moscow~A city in Russia; New York~New York city; London~London~Capital of England~green-marker.png;Brussels
}}

• Moscow, Russia~Moscow~A city in Russia: The address is followed by a title (Moscow), and a label (A city in Russia), and will therefore display a marker with both values.
• New York~New York city: This address only has a title parameter (New York city), and will not have any label, unless either title= or label= parameters are provided.
• London~London~Capital of England~green-marker.png: 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).
• Brussels: 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 title= or label= parameters are provided.

This is a stripped down example of one point and it's related data:

Address~Title~Label~Icon

[edit] Map services

Maps displaying an OpenLayers map with multiple base layers.

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

Maps displaying a Google Maps map with physical map type and a marker with pop-up.

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

[edit] Map properties

All map-display parser functions in Maps (display_map and display_point(s)) 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.

Both display_map and display_point(s) have a default property. This is the only value you can pass along without specifying the property name (like width=300). For display_map this is the coordinate or address representing the maps centre. For display_point(s) this is the list of points.

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

Example of a Yahoo! Maps map with several optional parameters.

{{
#display_points:
service=yahoomaps
|address=Moscow, Russia; New York City
|zoom=7
|width=800
|height=500
}}

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.

Mapping services:

Google Maps • Yahoo! Maps • OpenLayers • OpenStreetMap

[edit] 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.

[edit] 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: $egMapsAvailableServices = array('googlemaps', 'yahoomaps', 'openlayers', 'osm');

[edit] 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: $egMapsDefaultServices = array('pf' => 'googlemaps', 'qp' => 'googlemaps', 'fi' => 'googlemaps');

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: $egMapsDefaultService = 'googlemaps';

[edit] Available mapping features

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

[edit] Available geocoding services

Array containing all the geocoding services that will be made available to the user.

[edit] 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: $egMapsDefaultGeoService = 'geonames';

[edit] Default map coordinates

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

Default: $egMapsMapLat = '1'; $egMapsMapLon = '1';

[edit] Default map width

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

Default: $egMapsMapWidth = 600;

[edit] Default map height

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

Default: $egMapsMapHeight = 350;

[edit] Map size restrictions

The minimum and maximum width and height for all maps. First min, then max. Min needs to be smaller then max. When the height or width exceed their limits, they will be changed to the closest allowed value.

Default: $egMapsSizeRestrictions = array( 'width' => array( 100, 1000 ), 'height' => array( 100, 1000 ), );

[edit] 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.

[edit] Contributing to the project

[edit] 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.

[edit] 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.

[edit] 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.

[edit] Feature requests

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

[edit] 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.

[edit] Work for hire

The following people can be hired to set up a wiki that uses Maps and Semantic Maps, along with other MediaWiki components.

• Jeroen De Dauw - You can also hire me to develop new features for Maps or it's extensions, or do optimizations for your specific needs. Just send me an email.

[edit] 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.

[edit] 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!

• Hackerspace Brussels
• translatewiki.net
• Bluewater Wiki
• 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
• syn₂cat Hackerspace

[edit] External links

• Maps demo's

• Blog of the author about Maps and Semantic Maps

• Powerpoint presentation about Maps and Semantic Maps 0.4 used at Semantic MediaWiki Camp 2009.

[edit] See also

• Semantic MediaWiki
• Semantic Bundle
• Google Maps - A non-semantic Google Maps extension.
• Math Functions - Contains the function #geodistance, which calculates the distance between two coordinates.

Mapping services:

Google Maps • Yahoo! Maps • OpenLayers • OpenStreetMap

Maps:

Introduction • Download • Installation • Usage • Version history • Future work • Contributing • Extending Maps • Semantic Maps

Semantic Maps:

Introduction • Download • Installation • Usage • Version history • Future work • Contributing • Extending SM • Maps