Merge pull request mvexel#125 from KaartGroup/date_query

Add date parameter to query builder

Author: mvexel

README.md

@@ -54,7 +54,7 @@ response = api.get('node["name"="Salt Lake City"]')
 
 `response` will be a dictionary representing the
 JSON output you would get [from the Overpass API
-directly](https://overpass-api.de/output_formats.html#json). 
+directly](https://overpass-api.de/output_formats.html#json).
 
 **Note that the Overpass query passed to `get()` should not contain any `out` or other meta statements.** See `verbosity` below for how to control the output.
 
@@ -96,7 +96,12 @@ response = api.get('node["name"="Salt Lake City"]', responseformat="xml")
 
 We will construct a valid Overpass QL query from the parameters you set by default. This means you don't have to include 'meta' statements like `[out:json]`, `[timeout:60]`, `[out body]`, etcetera. You just supply the meat of the query, the part that actually tells Overpass what to query for. If for whatever reason you want to override this and supply a full, valid Overpass QL query, you can set `build` to `False` to make the API not do any pre-processing.
 
-### Pre-cooked Queries: `MapQuery`, `WayQuery` 
+#### `date`
+
+You can query the data as it was on a given date. You can give either a standard ISO date alone (YYYY-MM-DD) or a full overpass date and time (YYYY-MM-DDTHH:MM:SSZ, i.e. 2020-04-28T00:00:00Z).
+You can also directly pass a `date` or `datetime` object from the `datetime` library.
+
+### Pre-cooked Queries: `MapQuery`, `WayQuery`
 
 In addition to just sending your query and parse the result, `overpass`
 provides shortcuts for often used map queries. To use them, just pass

overpass/api.py

@@ -8,6 +8,7 @@
 import csv
 import geojson
 import logging
+from datetime import datetime
 from shapely.geometry import Polygon, Point
 from io import StringIO
 from .errors import (
@@ -42,8 +43,8 @@ class API(object):
     _debug = False
     _proxies = None
 
-    _QUERY_TEMPLATE = "[out:{out}];{query}out {verbosity};"
-    _GEOJSON_QUERY_TEMPLATE = "[out:json];{query}out {verbosity};"
+    _QUERY_TEMPLATE = "[out:{out}]{date};{query}out {verbosity};"
+    _GEOJSON_QUERY_TEMPLATE = "[out:json]{date};{query}out {verbosity};"
 
     def __init__(self, *args, **kwargs):
         self.endpoint = kwargs.get("endpoint", self._endpoint)
@@ -70,7 +71,7 @@ def __init__(self, *args, **kwargs):
             requests_log.setLevel(logging.DEBUG)
             requests_log.propagate = True
 
-    def get(self, query, responseformat="geojson", verbosity="body", build=True):
+    def get(self, query, responseformat="geojson", verbosity="body", build=True, date=''):
         """Pass in an Overpass query in Overpass QL.
 
         :param query: the Overpass QL query to send to the endpoint
@@ -81,11 +82,19 @@ def get(self, query, responseformat="geojson", verbosity="body", build=True):
                           "body geom qt"
         :param build: boolean to indicate whether to build the overpass query from a template (True)
                           or allow the programmer to specify full query manually (False)
+        :param date: a date with an optional time. Example: 2020-04-27 or 2020-04-27T00:00:00Z
         """
+        if date and isinstance(date, str):
+            # If date is given and is not already a datetime, attempt to parse from string
+            try:
+                date = datetime.fromisoformat(date)
+            except ValueError:
+                # The 'Z' in a standard overpass date will throw fromisoformat() off
+                date = datetime.strptime(date, '%Y-%m-%dT%H:%M:%SZ')
         # Construct full Overpass query
         if build:
             full_query = self._construct_ql_query(
-                query, responseformat=responseformat, verbosity=verbosity
+                query, responseformat=responseformat, verbosity=verbosity, date=date
             )
         else:
             full_query = query
@@ -137,18 +146,22 @@ def search(self, feature_type, regex=False):
     Get = get
     Search = search
 
-    def _construct_ql_query(self, userquery, responseformat, verbosity):
+    def _construct_ql_query(self, userquery, responseformat, verbosity, date):
         raw_query = str(userquery).rstrip()
         if not raw_query.endswith(";"):
             raw_query += ";"
 
+        if date:
+            date = f'[date:"{date.strftime("%Y-%m-%dT%H:%M:%SZ")}"]'
+
         if responseformat == "geojson":
             template = self._GEOJSON_QUERY_TEMPLATE
-            complete_query = template.format(query=raw_query, verbosity=verbosity)
+            complete_query = template.format(
+                query=raw_query, verbosity=verbosity, date=date)
         else:
             template = self._QUERY_TEMPLATE
             complete_query = template.format(
-                query=raw_query, out=responseformat, verbosity=verbosity
+                query=raw_query, out=responseformat, verbosity=verbosity, date=date
             )
 
         if self.debug: