Extension:GeoData

<languages/>

MediaWiki extensions manual

File:OOjs UI icon advanced-invert.svg Extension:GeoData Release status: stable[[Category:stable extensions{{#translation:}}]]
File:GeoData.png
Implementation
Description	<translate> Adds geographical coordinates storage and retrieval functionality</translate>
Author(s)	(MaxSemtalk)
Latest version
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki
PHP
Database changes
Composer
Tables	geo_tags
License
Download	<translate> Download extension</translate> <translate> Git</translate> [?]: <translate> Browse repository</translate> (Phabricator · GitHub) <translate> Gerrit code review</translate> <translate> Git commit log</translate> <translate> Download source tarball</translate> [[Category:Extensions in Wikimedia version control{{#translation:}}]]
Parameters
Added rights
Translate the Extension:GeoData extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug

[[Category:All extensions{{#translation:}}]]

<translate> The <tvar name=1>GeoData</tvar> extension allows articles to specify their geographical coordinates and publishes these coordinates via the HTTP <tvar name=2>API </tvar>.

Installation

Search backends

First of all, decide which search backend to use: </translate>

• <translate> MySQL (default): suitable for small to medium installs.</translate> <translate> Requires zero configuration.</translate> <translate> 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.</translate> <translate> Instead, it uses 0.1x0.1 degree tiles for search, which results in a slightly higher I/O, but faster updates.</translate>
• <translate> <tvar name=1>ElasticSearch</tvar> is a powerful search engine.</translate> <translate> When using ElasticSearch as a backend, GeoData works as a plugin for <tvar name=1>CirrusSearch </tvar> which adds ES text search to the wiki.</translate>

<translate>

Process

</translate>

• <translate> [[<tvar name=2>Special:ExtensionDistributor/GeoData</tvar>|Download]] and move the extracted <tvar name=name>GeoData</tvar> folder to your <tvar name=ext>extensions/</tvar> directory.</translate>
  <translate> Developers and code contributors should install the extension [[<tvar name=git>Special:MyLanguage/Download from Git</tvar>|from Git]] instead, using:</translate><syntaxhighlight lang="bash" copy="1">cd extensions/

git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/GeoData</syntaxhighlight>

• <translate> Add the following code at the bottom of your <tvar name=1>LocalSettings.php </tvar> file:</translate> <syntaxhighlight lang="php" copy="1">

wfLoadExtension( 'GeoData' );

</syntaxhighlight>

• <translate> Run the [[<tvar name=update>Special:MyLanguage/Manual:Update.php</tvar>|update script]] which will automatically create the necessary database tables that this extension needs.</translate>
• <translate> If you're about to use <tvar name=1>GeoData</tvar> with <tvar name=2>ElasticSearch</tvar>, {{<tvar name=3>ll|Extension:CirrusSearch#Installation</tvar>|install <tvar name=4>CirrusSearch</tvar>}} then add <tvar name=5><syntaxhighlight lang=php>$wgGeoDataBackend = 'elastic';</syntaxhighlight></tvar> to <tvar name=6>LocalSettings.php</tvar>, below the <tvar name=1>GeoData</tvar> loading.</translate>
• checkY <translate> Done</translate> – <translate> Navigate to <tvar name=special>Special:Version</tvar> on your wiki to verify that the extension is successfully installed.</translate>

<translate>

Usage

</translate> <translate> This extension adds a new {{<tvar name=1>ll|Manual:Parser functions</tvar>|parser function}}, <tvar name=2>{{#coordinates:}}</tvar>, that saves coordinates to the database.</translate> <translate> Function's input format is made as compatible as possible with <tvar name=1>GeoHack </tvar>.</translate>

<translate>

Glossary

</translate>

<translate> Coordinates</translate>

<translate> see w:geographical coordinates</translate>

<translate> Globe</translate>

<translate> terrestrial body on which the coordinate resides.</translate> <translate> By default, Earth is assumed.</translate> <translate> Internally, globe is represented as lowercase strings.</translate> <translate> The following globes are supported:</translate> 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, pluto. <translate> Globes not mentioned in this list will be assumed to have generic characteristics: longitude range 0-360°, Eastern longitude is positive.</translate> <translate> Longitude sign for known globes is taken [<tvar name=url>http://planetarynames.wr.usgs.gov/TargetCoordinates</tvar> according to IAU's conventions].</translate>

<translate> dim</translate>

<translate> approximate size of an object.</translate> <translate> Used by GeoData to restrict search and by GeoHack for determining appropriate map zoom.</translate> <translate> The default unit of measurement is metres, although the <tvar name=1>km</tvar> suffix may be appended to indicate kilometres.</translate>

<translate> Primary vs. secondary coordinates</translate>

<translate> primary coordinates define article subject's location, while secondary coordinates are other coordinates mentioned in the article.</translate> <translate> There can be only one primary coordinate per article, but as many secondaries as you like barring [[<tvar name=1>#Configuration settings</tvar>|technical restrictions]].</translate>

<translate>

Parser function

</translate> <translate> Function format:</translate>

{{#coordinates:<translate> latitude</translate>|<translate> longitude</translate>|[primary|][<translate> GeoHack parameters</translate>|][<translate> extra parameters</translate>]}}

<translate> Empty parameters (e.g. <tvar name=1>||</tvar> or <tvar name=2>| |</tvar>) are always ignored.</translate>

• <translate> latitude and longitude can be specified in several formats:</translate>
  • <translate> Direct signed input in degrees, e.g. <tvar name=1>37.786971|-122.399677</tvar>, which corresponds to <tvar name=2>37° 47′ 13.1″ N, 122° 23′ 58.84″ W</tvar>.</translate>

    <translate> As formatted number in the content language.</translate> <translate> Use <tvar name=1>{{formatnum:}}</tvar>, to format a number of a expression.</translate>

  • <translate> Degrees/minutes or degrees/minutes/seconds, e.g. <tvar name=1>37|47.2183|-122|23.9807</tvar> or <tvar name=2>37|47|13.1|-122|23|58.84</tvar>.</translate>
  • <translate> Either of the above, but with sign specified by N/E/S/W letters:</translate>

    37.786971|N|122.399677|W

    37|47.2183|N|122|23.9807|W

    37|47|13.1|N|-122|23|58.84|W

<translate> You should use either negative sign or N/E/S/W, but not both.</translate>

• <translate> <tvar name=2>primary</tvar> keyword specifies that these coordinates are primary (see [[<tvar name=1>#Glossary</tvar>|#Glossary]]).</translate>
• <translate> Extra parameters are any combination of the following named parameters:</translate>
  • <translate> <tvar name=2>dim</tvar>: [[<tvar name=1>#dim</tvar>|approximate size of the object]].</translate>
  • <translate> <tvar name=1>scale</tvar>: Scale of map display for this object, e.g. scale of 300 is 1:300.</translate> <translate> Gets converted into <tvar name=1>dim</tvar> internally using formula <tvar name=2>dim = scale / 10</tvar>.</translate> <translate> If both scale and dim are set, dim has precedence.</translate>
  • <translate> <tvar name=1>globe</tvar>, see [[<tvar name=2>#globe</tvar>|Glossary]].</translate>
  • <translate> <tvar name=1>name</tvar>: name of this point, up to 255 bytes (UTF-8).</translate>
  • <translate> <tvar name=1>region</tvar>: 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).</translate> <translate> This parameter is always capitalised internally.</translate>
  • <translate> <tvar name=1>type</tvar>: type of object with these coordinates, can be one of the following:</translate> country, satellite, state, adm1st, adm2nd, adm3rd, city, isle, mountain, river, waterbody, event, forest, glacier, airport, railwaystation, edu, pass, camera, landmark.

<translate> type</translate>	<translate> Description</translate>	<translate> Dim</translate>
country	(<translate> e.g. "<tvar name=1>type:country</tvar>"</translate>)	1,000,000
satellite	<translate> geo-stationary satellites</translate>	1,000,000
adm1st	<translate> Administrative unit of country, 1st level (province, state), e.g. U.S. states</translate>	1,000,000
adm2nd	<translate> Administrative unit of country, 2nd level, e.g. US county</translate>	30,000
adm3rd	<translate> Administrative unit of country, 3rd level</translate>	10,000
city(pop)	<translate> cities, towns, villages, hamlets, suburbs, subdivisions, neighborhoods, and other human settlements (including unincorporated and/or abandoned ones) with known population (optional population in braces is ignored)</translate>	10,000
airport	<translate> airports and airbases</translate>	3,000
mountain	<translate> peaks, mountain ranges, hills, submerged reefs, and seamounts</translate>	10,000
isle	<translate> islands and isles</translate>	10,000
waterbody	<translate> bays, fjords, lakes, reservoirs, ponds, lochs, loughs, meres, lagoons, estuaries, inland seas, and waterfalls</translate>	10,000
forest	<translate> forests and woodlands</translate>	5,000
river	<translate> rivers, canals, creeks, brooks, and streams, including intermittent ones</translate>	10,000
glacier	<translate> glaciers and icecaps</translate>	5,000
event	<translate> one-time or regular events and incidents that occurred at a specific location, including battles, earthquakes, festivals, and shipwrecks</translate>	5,000
edu	<translate> schools, colleges, and universities</translate>	1,000
pass	<translate> mountain passes</translate>	1,000
railwaystation	<translate> stations, stops, and maintenance areas of railways and trains, including railroad, metro, rapid transit, underground, subway, elevated railway, etc.</translate>	1,000
landmark	<translate> buildings (including churches, factories, museums, theatres, and power plants but excluding schools and railway stations), caves, cemeteries, cultural landmarks, geologic faults, headlands, intersections, mines, ranches, roads, structures (including antennas, bridges, castles, dams, lighthouses, monuments, and stadiums), tourist attractions, valleys, and other points of interest</translate>	1,000
	<translate> Default dim: if no type is used or the type is unknown to this extension</translate>	1,000

• <translate> GeoHack parameters: one or more pairs in format parameter:value, delimited by underscores (_) or spaces (e.g. <tvar name=1>dim:1000_type:city</tvar>).</translate> <translate> No spaces are allowed between parameter and colon or between colon and value.</translate> <translate> The parameters are the same as extra parameters above.</translate> <translate> If a parameter exists in both GeoHack parameters and extra parameters, extra parameters always have precedence.</translate> <translate> 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.</translate>

<translate>

Examples

</translate> <translate> Note how extra parameters are specified:</translate>

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

<translate>

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 [[<tvar name=1>Special:MyLanguage/MediaWiki:Geodata-broken-tags-category</tvar>|MediaWiki:Geodata-broken-tags-category]]):</translate>

• <translate> Coordinates out of range:</translate>

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

• <translate> Mixing coordinate signs and hemisphere letters:</translate>

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

• <translate> More than one primary coordinate on page:</translate>

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

• <translate> Too many coordinates on page: by default 500, 2000 on WMF.</translate>

<translate> The following errors are non-fatal by default:</translate>

• <translate> Unrecognised coordinate type:</translate>

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

<translate>

API

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

list=geosearch

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

Parameters:</translate>

Name	Description	Default
gscoord	<translate> Coordinate around which to search: two floating-point values separated by pipe (<tvar name=1>|</tvar>)</translate>
gsradius	<translate> Search radius in meters (10-10000).</translate> <translate> This parameter is required with the use of <tvar name=1>gscoord</tvar>.</translate>
gsbbox	left|bottom|right order.</translate>
gspage	<translate> Title of page around which to search</translate>
gsmaxdim	<translate> Restrict search to objects no larger than this, in meters</translate>
gslimit	<translate> Maximum number of pages to return.</translate> <translate> No more than 500 (5000 for bots) allowed.</translate>	10
gsglobe	<translate> Globe to search on.</translate>	earth
gsnamespace	<translate> Namespace(s) to search.</translate>	<translate> main namespace</translate>
gsprop	<translate> What additional coordinate properties to return.</translate> <translate> Values (separate with <tvar name=1>|</tvar>): type, name, country, region.</translate>
gsprimary	<translate> Whether to return only primary coordinates (<tvar name=1>primary</tvar>), secondary (<tvar name=2>secondary</tvar>) or both (<tvar name=3>all</tvar>).</translate>	primary

<translate> Example:</translate>

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

<translate> MediaWiki API result</translate>

<syntaxhighlight lang=json> {

   "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": ""
           }
       ]
   }

} </syntaxhighlight>

prop=coordinates

<translate> Returns coordinates of the given page(s)</translate>

<translate> Parameters:</translate>

Name	Description	Default
colimit	<translate> How many coordinates to return.</translate>
cocontinue	<translate> When more results are available, use this to continue.</translate>
coprop	<translate> What additional coordinate properties to return.</translate> <translate> Values (separate with <tvar name=1>|</tvar>): type, name, dim, country, region.</translate>
coprimary	<translate> Whether to return only primary coordinates (<tvar name=1>primary</tvar>), secondary (<tvar name=2>secondary</tvar>) or both (<tvar name=3>all</tvar>).</translate>	primary

<translate> Examples:</translate>

• <translate> Get a list of coordinates of the Wikimedia Foundation article:</translate>
  • api.php?action=query&prop=coordinates&titles=Wikimedia%20Foundation

<translate> MediaWiki API result</translate>

<syntaxhighlight lang=json> {

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

} </syntaxhighlight>

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

<translate> MediaWiki API result</translate>

<syntaxhighlight lang=json> {

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

} </syntaxhighlight>

<translate>

Enumerating pages with or without coordinates

</translate>

<translate> This functionality is not enabled on Wikimedia sites yet.</translate>

<translate> GeoData extends two core API modules, <tvar name=1>list=allpages </tvar> and <tvar name=2>list=categorymembers </tvar>.</translate> <translate> The extended modules are called <tvar name=1>geopages</tvar> and <tvar name=2>geopagesincategory</tvar>.</translate> <translate> It adds two mutually exclusive parameters, <tvar name=1>withcoordinates</tvar> and <tvar name=3>withoutcoordinates</tvar>.</translate>

<translate>

Configuration

</translate>

<translate> Setting</translate>	<translate> Type</translate>	<translate> Default</translate>	<translate> What is does</translate>
<syntaxhighlight inline="1" class="" style="" lang="php">$wgMaxGeoSearchRadius</syntaxhighlight>	<translate> int</translate>	10000	<translate> Maximum radius for geospatial searches, in meters.</translate> <translate> Reducing this value reduces server load</translate>
<syntaxhighlight inline="1" class="" style="" lang="php">$wgMaxCoordinatesPerPage</syntaxhighlight>	<translate> int</translate>	500	<translate> Maximum number of coordinates per page, -1 means no limit</translate>
<syntaxhighlight inline="1" class="" style="" lang="php">$wgTypeToDim</syntaxhighlight>	<translate> array</translate>	<translate> Long array, see the sources</translate>	<translate> Conversion table type --> dim</translate>
<syntaxhighlight inline="1" class="" style="" lang="php">$wgDefaultDim</syntaxhighlight>	<translate> array</translate>	1000	<translate> Default value of dim if it is unknown</translate>
<syntaxhighlight inline="1" class="" style="" lang="php">$wgGlobes</syntaxhighlight>	<translate> array</translate>	<translate> Long array, see the sources</translate>	<translate> Defines parameters of every globe</translate>
<syntaxhighlight inline="1" class="" style="" lang="php">$wgGeoDataWarningLevel</syntaxhighlight>	<translate> array</translate>	<syntaxhighlight lang="php">array( 'unknown type' => 'none', 'unknown globe' => 'none', 'invalid region' => 'none', )</syntaxhighlight>	<translate> Controls what GeoData should do when it encounters some problem. Reaction type:</translate> warn - <translate> Add tracking category</translate> fail - <translate> Consider the tag invalid, display message and add tracking category</translate> none - <translate> Do nothing</translate>
<syntaxhighlight inline="1" class="" style="" lang="php">$wgGeoDataIndexGranularity</syntaxhighlight>	<translate> int</translate>	10	<translate> How many integer units per degree to use with database-only search.</translate> <translate> Influences performance.</translate> <translate> Run updateIndexGranularity.php after changing this setting.</translate>
<syntaxhighlight inline="1" class="" style="" lang="php">$wgGeoDataBackend</syntaxhighlight>	<translate> string</translate>	'db'	<translate> Which backend should be used by spatial searches: 'db' or 'elastic'.</translate> <translate> Note if you're planning to change it, do so before creating the database tables.</translate>

[[Category:Skins used on Wikimedia{{#translation:}}|Extension:GeoData]]

<translate>

See also

</translate>

• [[Special:MyLanguage/Extension:Maps|Template:Translations:Extension:Maps/Page display title/en]] - <translate> Extension to visualize and work with geographical information.</translate>
• Semantic Result Formats - <translate> Various visualization formats for <tvar name=smw>[[Special:MyLanguage/Extension:Semantic MediaWiki|Template:Translations:Extension:Semantic MediaWiki/Page display title/en]] </tvar></translate>
• [[Special:MyLanguage/Extension:Kartographer|Template:Translations:Extension:Kartographer/Page display title/en]] - <translate> Allows displaying GeoJSON (so do recent versions of Maps)</translate>
• [[Special:MyLanguage/Extension:MultiMaps|Template:Translations:Extension:MultiMaps/Page display title/en]] - <translate> Allows users to display maps and coordinate data using multiple mapping services</translate>
• Extension:VisualData/Geolocation - <translate> Allows displaying <tvar name=1>Maptiler</tvar> maps in forms with reverse geocoding and draggable markers</translate>