Google Summer of Code/2015/Learning platform for Overpass

From OpenStreetMap Wiki
Jump to navigation Jump to search

Learning platform for Overpass API – LearnOverpass

The primary goal of this project is to make it easier for newcomers to learn and use the Overpass API for querying OSM data. This includes well structured documentation, guidelines, tutorials, learning courses, etc.

This GSoC project is currently in progress. The source code is found on github. More information about LearnOverpass and regular status updates can be found on Arian's personal blog.

Tutorials coverage

  • Overpass QL (query language), covering all simple cases
  • Output options for Overpass
  • Overpass Turbo: Export, MapCSS etc.
  • regular expressions

Features of learning platform

  • the end result should be fairly easy to edit should be fairly easy to edit by non-programmers
  • exercises and solution validation

Overpass API Learning Platform Writeup

This project aims to create a learning platform for the overpass API. Instead of reading dry old text, users will be able to learn the Overpass’ API usage in an interactive manner.

API/Syntax Reference

The API reference will serve as a one page reference for queries, detailing descriptions, parameter types, etc. of that particular query.

Query Parameter Description
poly space delimited coordinates an Array of points for the bounding polygon
node(poly:"x1 y1 x2 y2 x... y... xn yn");

It will also include an “embedded Overpass-Turbo”-like interface allowing learners to see how different queries are used, as well as making it easy to experiment with the methods and parameters themselves.

Exercise Mockup.png

Exercises

Interactive exercises allows users to learn different facets of the Overpass API in an easy and fun way.

Sample

Change the southern limit of the query to 50.540

node(50.746,50.532,50.748,50.231);
out body;

The exercises will follow a progressive format, while being fairly standalone.

Progressiveness will allow for the goal of equipping a complete beginner to become a competent user of the API, while keeping it standalone allows users who are confused only with certain tricky parts of Overpass API to be able to pick up what they need easily.

The exercises will be modelled as a merge between general, introductory material, as well as certain queries used in the real world.

Technical Details and Implementation

The learning platform will most likely be built using, but not limited to, the following frameworks and platforms:

Hugo - as the static site generator for the main site/reference API

Ace Editor - for the web based editor

React/Flux - as a front end framework/pattern

Gulp - Preprocessor

Deliverables Schedule

May 25 – 31

  • Bootstrap Application
  • Setup of necessary preprocessors (Gulp, Stylus, Coffeescript, etc.)
  • Setup of frameworks, etc. (Ace Editor, React, etc.)

June 1 - 7

  • Bring an embeddable version of Overpass Turbo to the site (through iFrame, custom scripts for REPL like interface, etc.)

June 8 - 19

  • Language Reference Creation
  • API Documentation/Reference creation

June 20 - 30

  • Polish reference pages
  • Prettify UI
  • Solicit User Feedback

July 1 - 10

  • Create Exercise Engine
  • Timeline based system (say this -> then this)
  • Output Correctness Checking

July 15 - August 15

  • Create Exercises

August 15 - 24

  • Extensive testing
  • Add Unit Tests
  • Solicit User Feedback
  • Add General Polish