Extension:GeoData

The GeoData extension allows articles to specify their geographical coordinates and publishes these coordinates via the HTTP API.

Search backends
First of all, decide which search backend to use:
 * MySQL (default): suitable for small to medium installs. Requires zero configuration. It does not use MySQL's built-in spatial indexes because when the extension was being developed, SPATIAL was pupprted only by MyISAM storage engine, which is worse than nothing. Instead, it uses 0.1x0.1 degree tiles for search, which results in a slightly higher I/O, but faster updates.
 * Elasticsearch is a powerful search engine. When using Elasticsearch as a backend, GeoData works as a plugin for CirrusSearch which adds ES text search to the wiki.

Process

 * Download and place the file(s) in a directory called GeoData in your  directory.
 * Add the following code at the bottom of your LocalSettings.php:


 * If you're about to use GeoData with Elasticsearch, install CirrusSearch then add  to LocalSettings.php, below the GeoData.php inclusion.
 * Run the updater to create the database table.
 * Done! Navigate to "Special:Version" on your wiki to verify that the extension is successfully installed.

Usage
This extension adds a new parser function,  , that saves coordinates to the database. Function's input format is made as compatible as possible with GeoHack.

Glossary

 * Coordinates - see here
 * Globe - terrestrial body on which the coordinate resides. By default, Earth is assumed. Internally, globe is represented as lowercase strings. The following globes are supported: earth, mercury, venus, moon, mars, phobos, deimos, ganymede, callisto, io, europa, mimas, enceladus, tethys, dione, rhea, titan, hyperion, iapetus, phoebe, miranda, ariel, umbriel, titania, oberon, triton and pluto. Globes not mentioned in this list will be assumed to have generic characteristics: longitude range 0-360°, Eastern longitude is positive. Longitude sign for known globes is taken according to IAU's conventions.
 * dim - approximate size of an object. Used by GeoData to restrict search and by Geohack for determining appropriate map zoom. The default unit of measurement is metres, although the km suffix may be appended to indicate kilometres.
 * Primary vs. secondary coordinates: primary coordinates define article subject's location, while secondary coordinates are other coordinates mentioned in the article. There can be only one primary coordinate per article, but as many secondaries as you like barring technical restrictions.

Parser function
Function format:
 *  


 * latitude and longitude can be specified in several formats:
 * Direct signed input in degrees, e.g. 37.786971|-122.399677, which corresponds to 37° 47′ 13.1″ N, 122° 23′ 58.84″ W.
 * As formatted number in the content language. Use, to format a number of a expression.
 * Degrees/minutes or degrees/minutes/seconds, e.g. 37|47.2183|-122|23.9807 or 37|47|13.1|-122|23|58.84.
 * Either of the above, but with sign specified by N/E/S/W letters:
 * 37.786971|N|122.399677|W
 * 37|47.2183|N|122|23.9807|W
 * 37|47|13.1|N|-122|23|58.84|W


 * primary keyword specifies that these coordinates are primary (see ).
 * Extra parameters are any combination of the following named parameters:
 * dim: approximate size of the object.
 * scale: Scale of map display for this object, e.g. scale of 300 is 1:300. Gets converted into dim internally using formula dim = scale / 10. If both scale and dim are set, dim has precedence.
 * globe, see.
 * name: name of this point, up to 255 bytes (UTF-8).
 * region: ISO 3166-1 alpha-2 country code (e.g. US or RU) or an ISO 3166-2 region code (e.g. US-FL or RU-MOS). This parameter is always capitalised internally.
 * type: type of object with these coordinates, can be one of the following: country, satellite, state, adm1st, adm2nd, adm3rd, city, isle, mountain, river, waterbody, event, forest, glacier, airport, railwaystation, edu, pass, camera, landmark.


 * GeoHack parameters: one or more pairs in format parameter:value, delimited by underscores (_) or spaces (e.g. dim:1000_type:city</tt>). No spaces are allowed between parameter and colon or between colon and value. The parameters are the same as extra parameters above. If a parameter exists in both GeoHack parameters and extra parameters, extra parameters always have precedence. This input is needed only for compatibilty with preexisting templates - if your wiki is only designing a geographical coordinates template, it is best if you not used raw GeoHack parameters at all.

Examples
Note how extra parameters are specified:

Error conditions
GeoData checks the data it receives for a number of error conditions.

The following conditions result in coordinates being outright rejected and added to tracking category (the name of it is defined by MediaWiki:Geodata-broken-tags-category):


 * Coordinates out of range:
 * Mixing coordinate signs and hemisphere letters:
 * More than one primary coordinate on page:
 * Too many coordinates on page: by default 500, 2000 on WMF.

The following errors are non-fatal by default:


 * Unrecognised coordinate type:

API
GeoData has two API modules that perform search around a given point and coordinates for a given article(s).

list=geosearch
Searches for articles around the given point (determined either by coordinates or by article name).

Parameters:


 * gscoord: Coordinate around which to search: two floating-point values separated by pipe (|)
 * gspage: Title of page around which to search
 * gsradius: Search radius in meters (10-10000). This parameter is required.
 * gsmaxdim: Restrict search to objects no larger than this, in meters
 * gslimit: Maximum number of pages to return. No more than 500 (5000 for bots) allowed. Default: 10. This aspect of GeoData won't quite work as you expect until an internal indexing problem is fixed (Bugzilla 49893). Until that time, GeoData returns a variable number of results that is always less than gslimit (and can be as little as 10% of gslimit) - you should request more results than you need and then trim the number of results in subsequent processing (according to T51893, this does not seem to be a problem when using ElasticSearch)
 * gsglobe: Globe to search on (by default earth</tt>).
 * gsnamespace: Namespace(s) to search. Default: main namespace.
 * gsprop: What additional coordinate properties to return. Values (separate with '|'): type, name, country, region.
 * gsprimary: Whether to return only primary coordinates (primary</tt>), secondary (secondary</tt>) or both (all</tt>). Default: primary</tt>.

Example:
 * Search around the point with coordinates 37° 47′ 13.1″ N, 122° 23′ 58.84″ W:
 * |-122.399677 api.php?action=query&list=geosearch&gsradius=10000&gscoord=37.786971|-122.399677

prop=coordinates
Returns coordinates of the given page(s)

Parameters:
 * colimit: How many coordinates to return.
 * cocontinue: When more results are available, use this to continue.
 * coprop: What additional coordinate properties to return. Values (separate with '|'): type, name, dim, country, region.
 * coprimary: Whether to return only primary coordinates (primary</tt>), secondary (secondary</tt>) or both (all</tt>). Default: primary</tt>.

Examples:
 * Get a list of coordinates of the Wikimedia Foundation article:
 * api.php?action=query&prop=coordinates&titles=Wikimedia%20Foundation


 * More qualified results (this is the query that Pywikibot uses.):
 * |name|dim|country|region&coprimary=all api.php?action=query&prop=coordinates&titles=Wikimedia%20Foundation&coprop=type|name|dim|country|region&coprimary=all

Enumerating pages with or without coordinates
GeoData extends two core API modules, list=allpages</tt> and list=categorymembers</tt>. The extended modules are called geopages</tt> and geopagesincategory</tt>. It adds two mutually exclusive parameters, withcoordinates</tt> and withoutcoordinates</tt>.