Skip to content

API : How does it work ?

Jump to bottom
Sylvain Arnouts edited this page Jun 5, 2016 · 3 revisions

Last update : 06 June 2016
Version : 1.0

Introduction

WikiJourney is based on two systems: a website and a mobile application. Both use data from Wikidata, Wikipedia and WikiVoyage; and though they do not do it exactly the same way, they are making the same requests to those websites. That's why we took the decision to separate the part of our code that's making requests to Wikidata's and Wikivoyage's API, to create our own API.

The application and the website thus send requests to a unique API, which contacts Wikidata, Wikipedia and WikiVoyage, finds informations, checks errors, and wraps those information a nice JSON object which can be sent back.

Our API is used by our mobile application and our website, but can also be used by anyone who needs those information for a project. No token is currently (06/06/2016) needed to access the API, though we may change that in a future version.

#How does it work?

First: decode GET query and get coordinates

Since the API parameters are sent out through URL, we first have to decode it. The user's input is secured. If the user has made a request which contains coordinates (longitude / latitude), we can call Wikimedia's API directly. If the user sent the name of a place instead, we need to find coordinates. To do so, we use the OpenStreetMaps nominatim system.

Contacting WikiVoyage API

We make a request to the API, using file_get_contents(). We then decode the JSON answer. If there are WikiVoyage guides around user's position, they are put in an array. Next, we create the output, which will contain, for each guide:

  • Title (depends on the chosen language)
  • Site link (depends on the chosen language)
  • Coordinates (if we want to put it on a map or something)
  • Link to thumbnail (if the option is enabled)

Fetching the POIs

First off, we call Wikipedia to find pages based on user's latitude and longitude. Then, we make a call to Wikipedia with those pages to get sitelink, thumbnail and Wikidata object id. Using this ID, we can fetch the type id, and then the type name by calling Wikidata.

Finally, in the output, we have, for each POI:

  • Wikipedia ID of the POI
  • Wikidata ID of the POI
  • Title of the POI
  • Coordinates
  • Distance in meters from user's position
  • Link to Wikipedia's page
  • Link to page's thumbnail
  • Type name and id (for example, a cemetery will return "cemetery" and "39614"). Those are very useful to create and display markers on the map.

In the end, we have an array containing those information for each POI.

For more details, please refer to the source code, or see the technical documentation here.

Error management

For each step, each network call, there is an error detection. If an error occurs, the value of err_check.value in the JSON return will be 'true'; the reason for that error can be found in err_check.err_msg.

Clone this wiki locally