API:Nearby places viewer

Overview
In this tutorial, you will learn how to search for wiki pages near your location using the MediaWiki Action API. Download the code from GitHub Browse the app on Toolforge This tutorial will teach you how to do this using:


 * Python and Flask framework
 * JavaScript, jQuery and Bootstrap framework
 * MediaWiki Action API's module
 * Geolocation API

A step-by-step process for building this application:

Step 1: Set up Python and Flask development environment
To set up the Python development environment for a Flask application, you will need to install Python, create a virtual environment and install Flask.

 Note:  This application uses Python3, the recommended version for new Python projects. Learn more about the differences between Python2 and Python3 here. To install Python3 on your local machine, follow step-by-step instructions in these [ https://docs.python-guide.org/starting/installation/#python-3-installation-guides installation guides].

Here is how to set up the development environment for building the application:

Render a simple static page
Place the following code in

Drop this one line of code in a HTML file inside the  folder:

 Note:  In this simple application, we are using method which renders the template named  from the  directory.

Next run your flask app with the command and open  to view your app in the browser. You should be able to see "Nearby places viewer" in your browser window.

Style your app
Let's do some app styling. Add a button element for accepting search input in the HTML file and link tags to load an external and internal stylesheet. External stylesheet, in this case, is the URL of a CSS file for a Google Font.

Replace the existing code in with the following:

Place the following code in

Application layout
$HOME/nearby-places-viewer ├── templates/ │  └── places.html ├── static/ │  └── static.css ├── nearby.py └── venv/

Step 3: Obtain coordinates of your current location
As a first step, to search for wiki pages nearby, you will need to obtain coordinates of your current location. To do so, you can use the Geolocation API along with some JavaScript code.

When you click the Click here to search button, the app makes a call to the Geolocation API and retrieves the current position of your device via the API's object. The API's response in return is a object from which you can obtain the latitude and longitude.

 Note:  When your app makes a call to the API you will be notified and asked to grant permission to your browser to access your location.

Place the following code in

Link the custom JavaScript and  from the  file:

Step 4: Send location data to the server with AJAX
This app uses jQuery's AJAX method to send the location data obtained in Step 3 to the server and POST it without page refresh to a Python Flask route in.

As a next step, let's add AJAX call to the function in.

 Note:  At this point, if you try to run your app, it is likely that you will see an error in the browser window as we have not added support to the route to handle post requests.

Step 5: Fetch nearby places via MediaWiki Action API
First, extend the Python Flask route in  to handle POST requests. You can do so by adding both GET and POST in the argument list in the route decorator. Next, you can obtain location data available in format from the  object and pass it to  function for further processing.

The code in the function makes a  request to the Action API to search for wiki pages near a location. API call consists of an endpoint and query string parameters. Some of the key parameters are:


 * main module to query information
 * query module's submodule  used as a  generator module to get search results for a set of pages
 * tells which properties to return for pages

 Note:  For more information on the geosearch module visit.

View complete Python and Flask code with import statements and processed list. This app uses package available in Python to calculate distance between two geographic coordinates.

Step 6: Create a user interface for list of places from JSON response
Handle the returned JSON data from the server in AJAX's callback and use HTML DOM  property to alter the  contents.

View complete JavaScript code with AJAX success callback.

Step 7: Style changes with Bootstrap
You might have noticed that the code snippet in Step 6 uses Bootstrap class names. Yes, we are integrating the Bootstrap framework at this step to add a responsive layout design to the Places UI. To do so, let's make some more tweaks to CSS and HTML files.

View complete CSS and HTML code.



Next steps

 * Got questions about this tutorial? [ https://discourse-mediawiki.wmflabs.org/c/ask-here Ask here on Discourse].
 * Contribute a demo app that you have developed using the MediaWiki API to this [ https://github.com/wikimedia/MediaWiki-Action-API-Code-Samples code samples repository].