implementing /contributions/count endpoint

CHANGELOG.md

@@ -3,6 +3,10 @@ Changelog
 
 ## 1.4.0-SNAPSHOT (current master)
 
+### New Features
+
+* add new endpoint /contributions/count/{density} ([#115])
+
 ### Bug Fixes
 
 * fix some invalid filters in the default swagger examples ([#111])
@@ -31,6 +35,7 @@ Changelog
 [#111]: https://github.com/GIScience/ohsome-api/issues/111
 [#113]: https://github.com/GIScience/ohsome-api/issues/113
 [#114]: https://github.com/GIScience/ohsome-api/pull/114
+[#115]: https://github.com/GIScience/ohsome-api/issues/115
 [#117]: https://github.com/GIScience/ohsome-api/issues/117
 [#129]: https://github.com/GIScience/ohsome-api/issues/129
 [#131]: https://github.com/GIScience/ohsome-api/issues/131

docs/endpoints.rst

@@ -8,8 +8,8 @@ API Endpoints
     The usage of the parameters **types**, **keys** and **values** is not recommended as they are deprecated. Please use the 
     filter_ parameter for your requests.
 
-Aggregation Endpoints
----------------------
+Elements Aggregation
+--------------------
 
 .. http:post :: /elements/(aggregation)
 
@@ -846,8 +846,8 @@ Compare length of different types of streets for two or more regions.
    * aggregation type: same as for **/elements/(aggregation)/groupBy/boundary/groupBy/tag**.
 
 
-Users Aggregation Endpoints
----------------------------
+Users Aggregation
+-----------------
 
 .. http:post :: /users/count
 
@@ -1021,9 +1021,227 @@ Show number of users editing buildings before, during and after Nepal earthquake
       }
 
 
-Extraction Endpoints
---------------------
+Contributions Aggregation
+-------------------------
+
+.. http:post :: /contributions/count
+
+   Get the count of the contributions provided to the OSM data. This endpoint does not support the deprecated ``types``, ``keys``, ``values`` parameters.
+
+.. note:: The /contributions/count endpoint is a new feature that is in the experimental status, meaning it is still under internal evaluation and might be subject to changes in the upcoming minor or patch releases.
+
+**Example request**:
+
+Number of contributions to the building 'Stadthalle Heidelberg' between 2010 and 2020.
+
+  .. tabs::
+
+    .. code-tab:: bash curl (GET)
+
+       curl -X GET 'https://api.ohsome.org/v1/contributions/count?bboxes=8.699053,49.411842,8.701311,49.412893&filter=id:way/140112810&time=2010-01-01,2020-01-01'
+
+    .. code-tab:: bash curl (POST)
+
+       curl -X POST 'https://api.ohsome.org/v1/contributions/count' --data-urlencode 'bboxes=8.699053,49.411842,8.701311,49.412893' --data-urlencode 'time=2010-01-01,2020-01-01' --data-urlencode 'filter=id:way/140112810'
+
+    .. code-tab:: python Python
+
+        import requests
+        URL = 'https://api.ohsome.org/v1/contributions/count'
+        data = {"bboxes": "8.699053,49.411842,8.701311,49.412893", "time": "2010-01-01,2020-01-01", "filter": "id:way/140112810"}
+        response = requests.post(URL, data=data)
+        print(response.json())
+
+    .. code-tab:: r R
+
+        library(httr)
+        r <- POST("https://api.ohsome.org/v1/contributions/count", encode = "form", body = list(bboxes = "8.699053,49.411842,8.701311,49.412893", time = "2010-01-01,2020-01-01", filter = "id:way/140112810"))
+        r
+
+
+**Example response**:
+
+  .. tabs::
+
+   .. code-tab:: json curl (GET)
+
+	{
+	  "attribution":{
+	    "url":"https://ohsome.org/copyrights",
+	    "text":"© OpenStreetMap contributors"
+	  },
+	  "apiVersion":"1.3.2",
+	  "result":[
+	    {
+	      "fromTimestamp":"2010-01-01T00:00:00Z",
+	      "toTimestamp":"2020-01-01T00:00:00Z",
+	      "value":15.0
+	    }
+	  ]
+	}
+
+   .. code-tab:: json curl (POST)
+
+	{
+	  "attribution":{
+	    "url":"https://ohsome.org/copyrights",
+	    "text":"© OpenStreetMap contributors"
+	  },
+	  "apiVersion":"1.3.2",
+	  "result":[
+	    {
+	      "fromTimestamp":"2010-01-01T00:00:00Z",
+	      "toTimestamp":"2020-01-01T00:00:00Z",
+	      "value":15.0
+	    }
+	  ]
+	}
+
+
+   .. code-tab:: json Python
+
+	{
+	  "attribution":{
+	    "url":"https://ohsome.org/copyrights",
+	    "text":"© OpenStreetMap contributors"
+	  },
+	  "apiVersion":"1.3.2",
+	  "result":[
+	    {
+	      "fromTimestamp":"2010-01-01T00:00:00Z",
+	      "toTimestamp":"2020-01-01T00:00:00Z",
+	      "value":15.0
+	    }
+	  ]
+	}
+
+   .. code-tab:: json R
+
+	{
+	  "attribution":{
+	    "url":"https://ohsome.org/copyrights",
+	    "text":"© OpenStreetMap contributors"
+	  },
+	  "apiVersion":"1.3.2",
+	  "result":[
+	    {
+	      "fromTimestamp":"2010-01-01T00:00:00Z",
+	      "toTimestamp":"2020-01-01T00:00:00Z",
+	      "value":15.0
+	    }
+	  ]
+	}
 
+
+.. http:post :: /contributions/count/density
+
+   Get the density of the count of contributions divided by the total area in square-kilometers. This endpoint does not support the deprecated ``types``, ``keys``, ``values`` parameters.
+
+**Example request**:
+
+Density of contributions to shops within the oldtown area of Heidelberg between 2012 and 2016.
+
+  .. tabs::
+
+    .. code-tab:: bash curl (GET)
+
+       curl -X GET 'https://api.ohsome.org/v1/contributions/count/density?bboxes=8.69282,49.40766,8.71673,49.4133&filter=shop=*%20and%20type:node&time=2012-01-01,2016-01-01'
+
+    .. code-tab:: bash curl (POST)
+
+       curl -X POST 'https://api.ohsome.org/v1/contributions/count/density' --data-urlencode 'bboxes=8.69282,49.40766,8.71673,49.4133' --data-urlencode 'time=2012-01-01,2016-01-01' --data-urlencode 'filter=shop=* and type:node'
+
+    .. code-tab:: python Python
+
+        import requests
+        URL = 'https://api.ohsome.org/v1/contributions/count/density'
+        data = {"bboxes": "8.69282,49.40766,8.71673,49.4133", "time": "2012-01-01,2016-01-01", "filter": "shop=* and type:node"}
+        response = requests.post(URL, data=data)
+        print(response.json())
+
+    .. code-tab:: r R
+
+        library(httr)
+        r <- POST("https://api.ohsome.org/v1/contributions/count/density", encode = "form", body = list(bboxes = "8.69282,49.40766,8.71673,49.4133", time = "2012-01-01,2016-01-01", filter = "shop=* and type:node"))
+        r
+
+
+**Example response**:
+
+  .. tabs::
+
+   .. code-tab:: json curl (GET)
+
+	{
+	  "attribution":{
+	    "url":"https://ohsome.org/copyrights",
+	    "text":"© OpenStreetMap contributors"
+	  },
+	  "apiVersion":"1.3.2",
+	  "result":[
+	    {
+	      "fromTimestamp":"2012-01-01T00:00:00Z",
+	      "toTimestamp":"2016-01-01T00:00:00Z",
+	      "value":417.13
+	    }
+	  ]
+	}
+
+   .. code-tab:: json curl (POST)
+
+	{
+	  "attribution":{
+	    "url":"https://ohsome.org/copyrights",
+	    "text":"© OpenStreetMap contributors"
+	  },
+	  "apiVersion":"1.3.2",
+	  "result":[
+	    {
+	      "fromTimestamp":"2012-01-01T00:00:00Z",
+	      "toTimestamp":"2016-01-01T00:00:00Z",
+	      "value":417.13
+	    }
+	  ]
+	}
+
+
+   .. code-tab:: json Python
+
+	{
+	  "attribution":{
+	    "url":"https://ohsome.org/copyrights",
+	    "text":"© OpenStreetMap contributors"
+	  },
+	  "apiVersion":"1.3.2",
+	  "result":[
+	    {
+	      "fromTimestamp":"2012-01-01T00:00:00Z",
+	      "toTimestamp":"2016-01-01T00:00:00Z",
+	      "value":417.13
+	    }
+	  ]
+	}
+
+   .. code-tab:: json R
+
+	{
+	  "attribution":{
+	    "url":"https://ohsome.org/copyrights",
+	    "text":"© OpenStreetMap contributors"
+	  },
+	  "apiVersion":"1.3.2",
+	  "result":[
+	    {
+	      "fromTimestamp":"2012-01-01T00:00:00Z",
+	      "toTimestamp":"2016-01-01T00:00:00Z",
+	      "value":417.13
+	    }
+	  ]
+	}
+
+
+Elements Extraction
+-------------------
 .. http:post :: /elements/(geometryType)
 
    Get the state of OSM data at the given timestamp(s) as a GeoJSON feature collection where object geometries are returned as the given ``geometryType`` (geometry, bbox, or centroid).
@@ -1289,8 +1507,8 @@ Extract the modifications of the blown up tower of the heidelberg castle over ti
       }
 
 
-Contribution Endpoints
-----------------------
+Contributions Extraction
+------------------------
 
 .. http:post :: /contributions/(geometryType)
 
@@ -1863,9 +2081,10 @@ Get the latest change of constructions in a certain area of the Bahnstadt in Hei
           }
         }]
       }
-
-Metadata Endpoint
------------------
+
+
+Metadata
+--------
 
 .. http:get :: /metadata
 

src/main/lombok/org/heigit/ohsome/ohsomeapi/config/SwaggerConfig.java

@@ -83,11 +83,12 @@ public Docket dataAggregationDocket() {
             .basePackage("org.heigit.ohsome.ohsomeapi.controller.dataaggregation"))
         .paths(PathSelectors.any()).build().apiInfo(apiInfo()).useDefaultResponseMessages(false)
         .globalOperationParameters(defineGlobalOperationParams(false))
-        .tags(new Tag("Users", "Compute data aggregation functions on users"),
-            new Tag("Area", "Compute the area of polygonal OSM elements"),
-            new Tag("Length", "Compute the length of linear OSM elements"),
-            new Tag("Count", "Compute the count of point/linear/polygonal OSM elements"),
-            new Tag("Perimeter", "Compute the perimeter of polygonal OSM elements"))
+        .tags(new Tag("Users Count", "Compute the count of OSM users"),
+            new Tag("Elements Area", "Compute the area of polygonal OSM elements"),
+            new Tag("Elements Length", "Compute the length of linear OSM elements"),
+            new Tag("Elements Count", "Compute the count of point/linear/polygonal OSM elements"),
+            new Tag("Elements Perimeter", "Compute the perimeter of polygonal OSM elements"),
+            new Tag("Contributions Count", "Compute the count of OSM contributions"))
         .forCodeGeneration(true).globalResponseMessage(RequestMethod.GET, responseMessages)
         .globalResponseMessage(RequestMethod.POST, responseMessages);
   }
@@ -116,8 +117,8 @@ public Docket dataExtractionDocket() {
         .paths(PathSelectors.any()).build().apiInfo(apiInfo()).useDefaultResponseMessages(false)
         .globalOperationParameters(defineGlobalOperationParams(true))
         .tags(new Tag("Elements Extraction", "Direct access to the OSM data"),
-            new Tag("Full-History Elements Extraction",
-                "Direct access to the full-history of the OSM data"),
+            new Tag("Full History Elements Extraction",
+                "Direct access to the full history of the OSM data"),
             new Tag("Contributions Extraction",
                 "Direct access to all contributions provided to the OSM data"))
         .forCodeGeneration(true).globalResponseMessage(RequestMethod.GET, responseMessages);

src/main/lombok/org/heigit/ohsome/ohsomeapi/controller/dataaggregation/contributions/ContributionsCountController.java

@@ -0,0 +1,67 @@
+package org.heigit.ohsome.ohsomeapi.controller.dataaggregation.contributions;
+
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import org.heigit.ohsome.ohsomeapi.executor.ContributionsExecutor;
+import org.heigit.ohsome.ohsomeapi.output.DefaultAggregationResponse;
+import org.heigit.ohsome.ohsomeapi.output.Response;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestMethod;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * REST controller containing the methods, which are mapped to "/contributions/count" and used to
+ * return the count of each contribution (creation, modification, deletion) of the OSM data.
+ */
+@Api(tags = "Contributions Count")
+@RestController
+@RequestMapping("/contributions/count")
+public class ContributionsCountController {
+
+  /**
+   * Gives the count of OSM contributions.
+   * 
+   * @param servletRequest <code>HttpServletRequest</code> of the incoming request
+   * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.DefaultAggregationResponse
+   *         DefaultAggregationResponse}
+   * @throws Exception thrown by
+   *         {@link org.heigit.ohsome.ohsomeapi.executor.ContributionsExecutor#count(boolean) count}
+   */
+  @ApiOperation(value = "Count of OSM contributions", nickname = "contributionsCount",
+      response = DefaultAggregationResponse.class)
+  @RequestMapping(value = "", method = {RequestMethod.GET, RequestMethod.POST},
+      produces = {"application/json", "text/csv"})
+  public Response contributionsCount(HttpServletRequest servletRequest,
+      HttpServletResponse servletResponse) throws Exception {
+    ContributionsExecutor executor =
+        new ContributionsExecutor(servletRequest, servletResponse, false);
+    return executor.count(false);
+  }
+
+  /**
+   * Gives the density of OSM contributions.
+   * 
+   * @param servletRequest <code>HttpServletRequest</code> of the incoming request
+   * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.DefaultAggregationResponse
+   *         DefaultAggregationResponse}
+   * @throws Exception thrown by
+   *         {@link org.heigit.ohsome.ohsomeapi.executor.ContributionsExecutor#count(boolean) count}
+   */
+  @ApiOperation(
+      value = "Density of OSM contributions (number of contributions divided by the "
+          + "total area in square-kilometers)",
+      nickname = "contributionsCountDensity", response = DefaultAggregationResponse.class)
+  @RequestMapping(value = "/density", method = {RequestMethod.GET, RequestMethod.POST},
+      produces = {"application/json", "text/csv"})
+  public Response contributionsCountDensity(HttpServletRequest servletRequest,
+      HttpServletResponse servletResponse) throws Exception {
+    ContributionsExecutor executor =
+        new ContributionsExecutor(servletRequest, servletResponse, true);
+    return executor.count(false);
+  }
+
+}