MediaWiki extensions manual

GeoData Release status: stable
Implementation	API,Parser function
Description	Adds geographical coordinates storage and retrieval functionality
Author(s)	Max Semenik (MaxSemtalk)
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki	1.25+
Database changes	Yes
Tables	geo_tags
License	WTFPL 2.0
Download	Download extension Git[?]: Browse repository (Phabricator · GitHub) Gerrit code review Git commit log Download source tarball
Parameters $wgGlobes $wgMaxCoordinatesPerPage $wgGeoDataIndexGranularity $wgMaxGeoSearchRadius $wgGeoDataRadiusScoreOverrides $wgDefaultDim $wgGeoDataWarningLevel $wgGeoDataInJS $wgGeoDataUseCirrusSearch $wgTypeToDim $wgGeoDataDebug $wgGeoDataBackend
Hooks used ArticleDeleteComplete CirrusSearchAddQueryFeatures FileUpload LinksUpdateComplete LoadExtensionSchemaUpdates OutputPageParserOutput ParserFirstCallInit SearchDataForIndex SearchDataForIndex2 SearchIndexFields
Translate the GeoData extension if it is available at translatewiki.net
Issues	Open tasks ·Report a bug

TheGeoData extension allows articles to specify their geographical coordinates and publishes these coordinates via the HTTPAPI.

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 supported 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 forCirrusSearch which adds ES text search to the wiki.

• Download and move the extractedGeoData folder to yourextensions/ directory.
  Developers and code contributors should install the extensionfrom Git instead, using:

  cdextensions/gitclonehttps://gerrit.wikimedia.org/r/mediawiki/extensions/GeoData

• Add the following code at the bottom of yourLocalSettings.php file:

  wfLoadExtension('GeoData');

• Run theupdate script which will automatically create the necessary database tables that this extension needs.
• If you're about to use GeoData with ElasticSearch,install CirrusSearch then add

  $wgGeoDataBackend='elastic';

  to LocalSettings.php, below the GeoData loading.
• Done – Navigate toSpecial:Version on your wiki to verify that the extension is successfully installed.

This extension adds a newparser function,{{#coordinates:}}, that saves coordinates to the database. Function's input format is made as compatible as possible withGeoHack.

• Coordinates - seew:geographical coordinates
• 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 andpluto. 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 takenaccording 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 barringtechnical restrictions.

Function format:

{{#coordinates:latitude|longitude|[primary|][GeoHack parameters|][extra parameters]}}

• latitude andlongitude 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{{formatnum:}}, to format a number of a expression.

  • Degrees/minutes or degrees/minutes/seconds, e.g.37|47.2183|-122|23.9807 or37|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#Glossary).
• 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 intodim internally using formuladim = scale / 10. If both scale and dim are set, dim has precedence.
  • globe, see#Glossary.
  • name: name of this point, up to 255 bytes (UTF-8).
  • region:ISO 3166-1 alpha-2 country code (e.g.US orRU) or anISO 3166-2 region code (e.g.US-FL orRU-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 formatparameter:value, delimited by underscores (_) or spaces (e.g.dim:1000_type:city). No spaces are allowed between parameter and colon or between colon and value. The parameters are the same asextra parameters above. If a parameter exists in both GeoHack parameters and extra parameters, extra parameters always have precedence. This input is needed only for compatibility with preexisting {{coord}} templates - if your wiki is only designing a geographical coordinates template, it is best if you not used raw GeoHack parameters at all.

Note how extra parameters are specified:

{{#coordinates:primary|40.775114|-73.968802|type:landmark_region:US-NY|name=Loeb Central Park Boathouse}}

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 byMediaWiki:Geodata-broken-tags-category):

• Coordinates out of range:

{{#coordinates:56|04|N|190|00|E}}{{#coordinates:76|61|03|N|37|25|30|W}}

• Mixing coordinate signs and hemisphere letters:

{{#coordinates:primary|-26|04|N|178|46|E}}{{#coordinates:primary|26.16|N|-178.76|E}}

• More than one primary coordinate on page:

{{#coordinates:primary|26|04|N|178|46|E}}{{#coordinates:primary|26|04|N|178|46|E}}

• Too many coordinates on page: by default 500, 2000 on WMF.

The following errors are non-fatal by default:

• Unrecognised coordinate type:

{{#coordinates:primary|26|04|N|178|46|E|type=New York}}{{#coordinates:primary|26|04|N|178|46|E|type:village}}

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

Searches for articles around the given point (determined either by coordinates, bounding box, or by article name).

Parameters:

gscoord

Coordinate around which to search: two floating-point values separated by pipe (|)

gsradius

Search radius in meters (10-10000). This parameter is required with the use of gscoord.

gsbbox

Bounding box to search in: pipe (|) separated coordinates of the corners in top|left|bottom|right order.

gspage

Title of page around which to search

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.

gsglobe

Globe to search on (by defaultearth).

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), secondary (secondary) or both (all). Default:primary.

Example:

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

{"batchcomplete":"","query":{"geosearch":[{"pageid":9292891,"ns":0,"title":"140 New Montgomery","lat":37.7868194444444,"lon":-122.399905555556,"dist":26.2,"primary":""},{"pageid":40377676,"ns":0,"title":"New Montgomery Street","lat":37.78729,"lon":-122.40033,"dist":67.5,"primary":""},{"pageid":1544800,"ns":0,"title":"Cartoon Art Museum","lat":37.787088,"lon":-122.40094,"dist":111.7,"primary":""},{"pageid":2183989,"ns":0,"title":"Academy of Art University","lat":37.78785,"lon":-122.40065,"dist":129.9,"primary":""},{"pageid":24801569,"ns":0,"title":"SPUR (San Francisco organization)","lat":37.78716,"lon":-122.4012,"dist":135.5,"primary":""},{"pageid":9297181,"ns":0,"title":"101 Second Street","lat":37.788139,"lon":-122.399056,"dist":140.9,"primary":""},{"pageid":40413203,"ns":0,"title":"222 Second Street","lat":37.78635,"lon":-122.39825,"dist":143.2,"primary":""},{"pageid":20004112,"ns":0,"title":"The Montgomery (San Francisco)","lat":37.78762,"lon":-122.40112,"dist":145.9,"primary":""},{"pageid":18679821,"ns":0,"title":"California Historical Society","lat":37.78684444444444,"lon":-122.40148055555557,"dist":159.1,"primary":""},{"pageid":71882190,"ns":0,"title":"St. Regis Museum Tower","lat":37.7863,"lon":-122.4013,"dist":161,"primary":""}]}}

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), secondary (secondary) or both (all). Default:primary.

Examples:

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

{"batchcomplete":"","query":{"pages":{"18618509":{"pageid":18618509,"ns":0,"title":"Wikimedia Foundation","coordinates":[{"lat":37.78916667,"lon":-122.40333333,"primary":"","globe":"earth"}]}}}}

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

{"batchcomplete":"","query":{"pages":{"18618509":{"pageid":18618509,"ns":0,"title":"Wikimedia Foundation","coordinates":[{"lat":37.78916667,"lon":-122.40333333,"primary":"","type":"landmark","dim":"1000"}]}}}}

GeoData extends two core API modules,list=allpages andlist=categorymembers. The extended modules are calledgeopages andgeopagesincategory. It adds two mutually exclusive parameters,withcoordinates andwithoutcoordinates.

array('unknown type'=>'none','unknown globe'=>'none','invalid region'=>'none',)

This extension is being used on one or moreWikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia'sCommonSettings.php andInitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki'sSpecial:Version page.

This extension is included in the following wiki farms/hosts and/or packages: Miraheze MyWikis ProWiki WikiForge This is not an authoritative list.Some wiki farms/hosts and/or packages may contain this extension even if they are not listed here.Always check with your wiki farms/hosts or bundle to confirm.

• Stable extensions
• API extensions
• Parser function extensions
• WTFPL licensed extensions
• Extensions in Wikimedia version control
• ArticleDeleteComplete extensions
• CirrusSearchAddQueryFeatures extensions
• FileUpload extensions
• LinksUpdateComplete extensions
• LoadExtensionSchemaUpdates extensions
• OutputPageParserOutput extensions
• ParserFirstCallInit extensions
• SearchDataForIndex extensions
• SearchDataForIndex2 extensions
• SearchIndexFields extensions
• All extensions
• Extensions used on Wikimedia
• Extensions included in Miraheze
• Extensions included in MyWikis
• Extensions included in ProWiki
• Extensions included in WikiForge

• Extensions with release branches compatibility policy
• Extensions with manual MediaWiki version