API:Geosearch

From MediaWiki.org
Jump to navigation Jump to search
Other languages: English

GET Request to search for wiki pages near a location with geographic coordinates or page name.

This module is supported through the Extension:GeoData currently not installed on MediaWiki but Wikipedia. So, in this document, we will use the URL en.wikipedia.org in all API endpoints.

API documentation[edit]

View the complete documentation and list of supported parameters here.

Examples[edit]

Example 1: Obtain coordinates[edit]

GET Request[edit]

Obtain coordinates of Wikimedia Foundation headquarters by providing the article title:

Response[edit]

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

Sample code[edit]

geocoordinates.py

#!/usr/bin/python3

"""
    geocoordinates.py

    MediaWiki Action API Code Samples
    Demo of `Geosearch` module: Obtain coordinates for wiki pages nearby
    MIT license
"""

import requests

S = requests.Session()

URL = "https://en.wikipedia.org/w/api.php"

TITLE = 'Wikimedia Foundation'

PARAMS = {
    'action':"query",
    'prop':"coordinates",
    'titles': TITLE,
    'format':"json"
}

R = S.get(url=URL, params=PARAMS)
DATA = R.json()
PAGES = DATA['query']['pages']

for k, v in PAGES.items():
    print("Latitute: " + str(v['coordinates'][0]['lat']))
    print("Longitude: " + str(v['coordinates'][0]['lon']))

Example 2: Search for pages nearby[edit]

GET Request[edit]

Search for pages near Wikimedia Foundation headquarters by specifying the geographic coordinates of its location:

Response[edit]

Sample code[edit]

Example 3: Search for pages nearby with images[edit]

GET Request[edit]

As an enhancement to Example 2, here we use the Generator module to get search results for pages near Wikimedia Foundation headquarters with images. Parameters passed along with a generator must be prefixed with a g.

Note that in the query below, we've changed gscoord to ggscoord.

Response[edit]

Sample code[edit]

Demo app(s)[edit]

  • Special:Nearby on English Wikipedia shows articles of places around you
    Screenshot of Wikipedia IOS app - shows places around Wikimedia Foundation HQ
  • Wikipedia Mobile Apps use this API to show nearby locations. API usage can be seen in the source code of Android and IOS app
  • Nearby is an app for the Pebble smart watch that fetches Wikipedia articles near you.

Possible errors[edit]

Code Info
invalid-coord Invalid coordinate provided (Latitude and Longitude should be separated by pipe (|) symbol)

Additional notes[edit]

  • This module is supported through the Extension:GeoData, currently installed on Wikimedia Commons, all Wikipedias, all Wikivoyage sites, and some other wikis. You can use Special:Version of a wiki to check if the extension is listed there.
  • In addition to using the API as to ask for a page coordinates (as explained in Example 1), here are a few more ways to obtaining them:
    • If you want your user's current location, it's available through many OS-specific APIs. Recent browsers have an opt-in navigator.geolocation object. See MDN docs.
    • If you want the user to provide coordinates, there are various services that let the user pick from a map. See w:Wikipedia:Obtaining geographic coordinates.

See also[edit]