API:Showing nearby wiki information

From MediaWiki.org
Jump to navigation Jump to search
Plug-in Noun project 4032.svg This page is part of the Web APIs hub.


This shows how to query the MediaWiki API for nearby articles.

Nearby feature in Wikipedia mobile view in Firefox Android browser

How it works in MediaWiki[edit]

The GeoData extension provides a query list submodule for geosearch. As of April 2015 it is installed on commons, all Wikipedias, all Wikivoyage sites, and some other wikis. Use Special:Version to check. This finds wiki pages with associated geographic coordinates "near" a location. You can either give the geographic coordinates of a location, or a wiki page name that has its own geographic coordinates. The mobile view on those wikis exposes this capability as "Nearby" in the Wikipedia menu, as shown in the screenshot.

Let's perform a geosearch for pages near the Wikimedia Foundation offices

With just the coordinates and page name you can present a list of pages nearby.

Getting additional information in one query request[edit]

Page names alone are ambiguous and perhaps not exciting. Just as with search results, you can query the page names returned for a pageimage and a description. Also just as with search results, you generally get better performance by making fewer queries; ideally you make a single API request to get all the information you want to display. Since a list query can also act as a Generator, you can do this: specify generator=geosearch. The list of pages from the generator become the set of pages for the other part of the query, all in a single API request.

Note we change the geosearch gszzz parameters to ggszzz, since they are now parameters to the generator "geosearch".

How to get geographic coordinates[edit]

The queries above hardcode the coordinates (37.786952, -122.399523). In practice you either want to show something near your user, or near some other known item.

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 en:Wikipedia:Obtaining geographic coordinates.

If there's a page describing a feature nearby, that page may provide coordinates for the feature. In the case of the en:Eiffel Tower, some editor added {{coord|48|51|29.6|N|2|17|40.2|E}} markup to the page. This markup both displays the coordinates (and on English Wikipedia the MWikiMiniAtlas JavaScript library turns them into a clickable, draggable map) and causes GeoData's {{#coordinates:}}to be called. You can programmatically ask for a page's coordinates using Geodata's other API, a page property query submodule action=query&prop=coordinates:

If you want to show items near an article, you can simply provide the article title to the geosearch as a gspage=Some page name parameter instead of geographic coordinates in the gscoords=latitude|longitude parameter:

Going beyond[edit]

The Wikipedia mobile apps show a compass pointing at the nearby locations. To do this you need to obtain the orientation of the device.

"Nearby" feature in Wikipedia Beta Android app, cropped

Other languages and Wikidata[edit]

This works well in English because English Wikipedia has many articles that have a coordinates property. Other languages may have far fewer articles with coordinates.

The ultimate resolution of this is to store coordinates as properties of language-independent items in Wikidata. Then you can present items nearby in any language. If you follow the "Wikidata item" link in the sidebar of English Wikipedia's 140 New Montgomery Street, you can see that wikidata:Q14681501 does have a "coordinate location" (property P625), which turns out to be imported from this Wikipedia article.

The Wikidata query service has a special extension called wikibase:around that is available in SPARQL queries. Here's an example of a comparable query to the first example mentioned in this document (items near the Wikimedia Foundation offices). Note that the coordinates provided to this query are switched around compared to the GeoData API call.

Next steps[edit]

Try these API requests in the Special:ApiSandbox, then make the same API requests from your own applications.

Try mashing up OpenStreetMaps with these locations.

Make a game where you have to come up with a wiki page name as close to a given page as possible.

See also[edit]