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]

Python[edit]

#!/usr/bin/python3

"""
    geocoordinates.py

    MediaWiki API Demos
    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"

PARAMS = {
    "action": "query",
    "format": "json",
    "titles": "Wikimedia Foundation",
    "prop": "coordinates"
}

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']))

PHP[edit]

<?php
/*
    geocoordinates.php

    MediaWiki API Demos
    Demo of `Geosearch` module: Obtain coordinates for wiki pages nearby

    MIT License
*/

$endPoint = "https://en.wikipedia.org/w/api.php";
$params = [
    "action" => "query",
    "prop" => "coordinates",
    "titles" => "Wikimedia Foundation",
    "format" => "json"
];

$url = $endPoint . "?" . http_build_query( $params );

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
$output = curl_exec( $ch );
curl_close( $ch );

$result = json_decode( $output, true );

foreach( $result["query"]["pages"] as $k => $v ) {
    echo("Latitute: " . $v["coordinates"][0]["lat"] . "\n" );
    echo("Longitude: " . $v["coordinates"][0]["lon"] . "\n" );
}

Javascript[edit]

/*
    geocoordinates.js

    MediaWiki API Demos
    Demo of `Geosearch` module: Obtain coordinates for wiki pages nearby

    MIT License
*/

var url = "https://en.wikipedia.org/w/api.php"; 

var params = {
    action: "query",
    prop: "coordinates",
    titles: "Wikimedia Foundation",
    format: "json"
};

url = url + "?origin=*";
Object.keys(params).forEach(function(key){url += "&" + key + "=" + params[key];});

fetch(url)
    .then(function(response){return response.json();})
    .then(function(response) {
        var pages = response.query.pages;
        for (var page in pages) {
            console.log("Latitute: " + pages[page].coordinates[0].lat);
            console.log("Longitude: " + pages[page].coordinates[0].lon);
        }
    })
    .catch(function(error){console.log(error);});

MediaWiki JS[edit]

/*
	geocoordinates.js

	MediaWiki API Demos
	Demo of `Geosearch` module: Obtain coordinates for wiki pages nearby

	MIT License
*/

var params = {
		action: 'query',
		prop: 'coordinates',
		titles: 'Wikimedia Foundation',
		format: 'json'
	},
	api = new mw.Api();

api.get( params ).done( function ( data ) {
	var pages = data.query.pages,
		page;
	for ( page in pages ) {
		console.log( 'Latitute: ' + pages[ page ].coordinates[ 0 ].lat );
		console.log( 'Longitude: ' + pages[ page ].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]