Semantic Maps

• Download MapsAndSemanticMaps0.2 - 307.28 KB

Introduction 

Semantic Maps is an extension that adds semantic capabilities to the Maps extension, and therefore provides the ability to add, view and edit coordinate data stored through the Semantic MediaWiki extension, using multiple mapping services. These services include Google Maps, OpenLayers and Yahoo Maps. Semantic Maps and Maps are based on Semantic Google Maps and Semantic Layers, and are meant to replace these extensions. For this extension to work, you need to have both Semantic MediaWiki and Maps installed. Examples of how to use Semantic Maps can be found here.

Maps is an extension that provides the ability to display coordinate data, using multiple mapping services, including Google Maps, OpenLayers and Yahoo Maps, and allows users to geocode addresses. It can be used together with Semantic Maps, which adds semantic capabilities to the mapping services, but can also be used without it on non-semantic wiki's. 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. Examples of how to use Maps can be found here.

Background 

I developed these extensions as my Google Summer of Code project this year. This means Google payed me to create them for Wikimedia Foundation. I regularly posted about my experiences in creating these extensions on my blog, click here to view the relevant posts.

Downloads 

• Maps0.2.zip 281.03 KB
• Maps0.2.7z 188.08 KB

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

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

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

Maps and Semantic Maps

• MapsAndSemanticMaps0.2.zip 307.28 KB
• MapsAndSemanticMaps0.2.7z 198.3 KB

Semantic Bundle

Semantic Bundle currently includes Maps and Semantic Maps 0.2, as well as some other very interesting Semantic MediaWiki related extensions. Get it here. 

Installation instructions

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, you can add a link to your site to the Who is using maps? section.  

Usage

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.

{{#display_point:coordinates=55.7557860, 37.6176330}}

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

{{#display_point:55.7557860, 37.6176330}}

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.

{{#geocode:Moscow, Russia}}

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

{{ #display_point:coordinates={{#geocode:Moscow, Russia}} }}

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.

{{#display_address:address=Moscow, Russia}}

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

{{#display_address:Moscow, Russia}}

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}}

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

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

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:

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

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

Display multiple points

You can set a Semantic MediaWiki #ask query to display its results as a map, by setting "format=mapservice", in which 'mapservice' is the mapping service you want to use. You can use all of the available mapping services of Maps. See the Map formats list for the exact names of the formats. One of the properties queried and displayed must be of type 'Geographic coordinate' for this query to work; this property is what will determine the location of each point on the map. Clicking on each point will display a label holding the name of the page, along with any other queried information; clicking on the page name will bring the user to that page. The zoom level of the map will be the closest one possible that shows all the points.

Both maps that result from the following code will have markers on the same locations, but will use different mapping services. To recreate such a result, you simply make a category with the name Locations, which has a property 'Has coordinates', of type Geographic coordinate. Demo with the example.

{{#ask:[[Category:Locations]]|?Has coordinates|format=map}}

Map services 

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.

• service=googlemaps or service=google - Click here for an overview of Google Maps functionality. Examples.
• service=yahoomaps or service=yahoo - Click here for an overview of Yahoo Maps functionality. Examples.
• service=openlayers or service=layers - Click here for an overview of OpenLayers functionality. Examples.

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

Each service has it's own unique functionality. Click the service name above for an overview of these features. See the list below for the common parameters.

Maps Map properties

Both the #display_point and #display_address parser functions accept the following list of map properties, which can be altered to change the appearance and usage of the resulting map. This list contains only the common parameters, in other words, the parameters that can be used for every mapping service. For the specific parameters, see the map services.

• coordinates= - (display_point only) the coordinates to display a marker and also the centre of the map - you can set the default
• address= - (display_address only) the address to display a marker and also the centre of the map
• width= - the width of the map, in pixels - you can set the default
• height= - the height of the map, in pixels - you can set the default
• zoom= - the zoom level of the map - you can set the default
• centre= or center= - the coordinates of the map's centre. When not provided, the map will centre itself on the provided (or default) coordinates/address.
• title= - text that will be displayed in a pop-up when the marker representing the location is clicked. When used together with label, the title will be bold and have a line under it.
• label= - text that will be displayed in a pop-up when the marker representing the location is clicked.

Example of a Yahoo! Map:

{{
#display_address:
service=yahoomaps
|address=Moscow, Russia
|zoom=7
|width=800
|height=500
}}

Semantic Maps Map properties

You can add seven additional parameters to the query, to change the appearance and usage of the resulting map.

To make it really easy for you, Semantic Maps uses the same names as Maps (see Map's map properties) where possible. There are however some differences.

Result formats

• coordinates= - (display_point only) the coordinates to display a marker and also the centre of the map - you can set the default
• address= - (display_address only) the address to display a marker and also the centre of the map
• width= - the width of the map, in pixels - you can set the default
• height= - the height of the map, in pixels - you can set the default
• centre= or center= - the coordinates of the map's centre. When not provided in a query, the map will centre itself to show all points.
• zoom= - the map's zoom level. When not provided in a query, this will default to the maximal zoom that allows all points to be displayed.

Here is an example of an #ask query that uses the 'googlemaps' format (view demo's):

{{
#ask:
[[Category:Locations]]
|?Has coordinates
|format=googlemaps
|width=800
|height=500
|zoom=8
|autozoom=off
}}

Form inputs

• width= - the width of the map, in pixels - you can set the default
• height= - the height of the map, in pixels - you can set the default
• zoom= - the zoom level of the map. When not provided, this will default to a view of the entire planet - you can set the default
• centre= or center= - the coordinates of the map's centre. When not provided, the map will centre itself on the current location (when no location is set yet, on coordinates 0,0).

Querying non-coordinate data

Semantic Maps supports the display of queried non-coordinate data. All queried properties that are not coordinates will be displayed in a pop-up balloon that will appear when clicking the marker representing the location of their corresponding coordinates. If there is a page associated with one of the non-coordinate values, the value will be linked to it. 

Form Inputs 

Semantic Maps provides multiple form inputs. Form inputs are hooks for Semantic Forms. Every mapping service has it's own form input. The form input type is determined with the input type parameter.

• input type=map - the default mapping service will be used.
• input type=googlemaps - Google Maps service.
• input type=yahoomaps - Yahoo Maps service.
• input type=openlayers - OpenLayers service.

Each service has it's own unique functionality. Click the service name above for an overview of these features. See the map properties below for the common parameters.

Geocoding locations in the form input

This feature is only available for maps using the Google Maps or Yahoo! Maps mapping services. OpenLayers form inputs will not have it. 

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

Default mapping service

The default mapping 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 services will be taken.

Default: $egMapsDefaultService = 'googlemaps';

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: $egMapsAvailableGeoServices = array('google', 'yahoo');

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 = 'google';

Default map coordinates

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

Default: $egMapsMapCoordinates = '1,1';

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;

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;

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.

Version

Maps is currently at version 0.2. It is still be considered beta, since some issues might be present. However, it has been tested quite thoroughly, and should not cause any big problems. An update to this version can be expected within a few weeks, adding more functionality, fixing bugs and improving the overall extension structure.

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.2 (2009-07-29)

Version 0.1 (2009-07-20)

Contributing to the project

Bugs and patches

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.

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.