Extension:Maps/geocoding service

From semantic-mediawiki.org
Extension "Maps"Extension:Maps/geocoding service


According to Wikipedia (retrieved Aug 2013), Geocoding is the process of finding associated geographic coordinates (often expressed as latitude and longitude) from other geographic data, such as street addresses, or ZIP codes (postal codes). With geographic coordinates the features can be mapped and entered into Geographic Information Systems, or the coordinates can be embedded into media such as digital photographs via geotagging.

A geocoding service allows to submit an address and it will return geographic coordinates in various formats. Addresses can be complete or partial (e.g. just a city name) and they can be Zips. Such services exist in different form. For example, the Google Geocoding API provides a direct way to access its geocoding services via an HTTP request and that is used by the Maps extension.

A reverse geocoding service allows to submit coordinates and retrieve the closest human-readable address.

By default, Maps uses the Google API. If you get more than 2500 hits/day you should acquire a commercial license for Google or configure Maps to use the Geonames services (see below).

Implemented services in Maps 3.0x

(just by looking at the code)

Google geocoding

This service implements both geocoding with an address and reverse geocoding. Read The Google Geocoding API for details (that you don't need to know if you use Maps ....)


Input parameters for geocoding:


Output parameters

  • Output can be JSON or XML and it will include all sorts of information, including the coordinates of course. Maps uses XML

Example request


According to the documentation, "Use of the Google Geocoding API is subject to a query limit of 2,500 requests per day. (User of Google Maps API for Business 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.

Also, the Geocoding API may only be used in conjunction with a Google map; geocoding results without displaying them on a map is prohibited.

Maps implementation

By default, Maps will use the Google API. However, you also can explicitly define Google geocoding

{{#geocode:New York|service=google}}

Geonames geocoding

Geonames provides a number of web services that also are available via a REST API. Using a service requires a (free) username and password. 30'000 credits daily limit per application (identified by the parameter 'username'), the hourly limit is 2000 credits. Hopefully, no more than 2000 people will look at this page.

API URL (only works if you set up an account)


The API documentation (GeoNames Search Webservice description), defines a number of parameters. q will search through all attributes of a place and this is what Maps (3.0 alpha) seems to be using.

Working example (some day the username should be substituted by one that belongs to semantic-mediawiki.org)


Not working:

URLS that use special characters. Instead you will have to URL encode, e.g. replace blanks by "+". The Maps extension will automatically URL encode these.

Maps implementation

In order to use this service with the Maps extensions, you must:

After doing so, GeoNames automatically becomes the default. In that case if you still wish to use the Google API in some cases, you should explicitly ask for it, i.e. use service=google