Merge branch 'master' into histograms

README.md

@@ -6,3 +6,13 @@
 Our API is documented using the [Swagger](http://swagger.io/)/[OpenAPI](https://github.com/OAI/OpenAPI-Specification) 2.0 [specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md). Check out the [Swagger UI](https://github.com/swagger-api/swagger-ui) documentation viewer at http://api.inaturalist.org/docs.
 
 #### http://api.inaturalist.org
+
+# Running Tests
+
+Run all: `npm test`
+Filter by pattern: `NODE_ENV=test ./node_modules/mocha/bin/_mocha --recursive --fgrep observations`
+
+# Updating Documentation
+
+Edit `lib/views/swagger_v*.yml.ejs`
+

lib/controllers/v1/observations_controller.js

@@ -379,6 +379,12 @@ ObservationsController.reqToElasticQueryComponents = function( req, callback ) {
       "taxon.ancestor_ids", params.taxon_id || params.taxon_ids ) );
   }
 
+  if( params.without_taxon_id ) {
+    search_filters.push( { not: {
+      terms: { "taxon.ancestor_ids": util.paramArray( params.without_taxon_id ) }
+    }});
+  }
+
   if( params.verifiable == "true" ) {
     search_filters.push(
       esClient.termFilter( "quality_grade", [ "needs_id", "research" ] ) );

lib/views/_observation_search_params_v1.yml.ejs

@@ -31,6 +31,7 @@
         - $ref: "#/parameters/site_id"
         - $ref: "#/parameters/sound_license"
         - $ref: "#/parameters/taxon_id"
+        - $ref: "#/parameters/without_taxon_id"
         - $ref: "#/parameters/taxon_name"
         - $ref: "#/parameters/user_id"
         - $ref: "#/parameters/user_login"

lib/views/swagger_v1.yml.ejs

@@ -24,6 +24,9 @@ info:
     [developers page](http://www.inaturalist.org/pages/developers) for more
     information.
 
+    Multiple values for a single parameter should be separated by commas, e.g.
+    `taxon_id=1,2,3`.
+
     Map tiles are generated using the
     [node-mapnik](https://github.com/mapnik/node-mapnik) library, following the
     XYZ map tiling scheme. The "Observation Tile" methods accept nearly all the
@@ -1047,7 +1050,15 @@ parameters:
       type: string
     in: query
     minimum: 1
-    description: Taxon must have this ID
+    description: Only show observations of these taxa and their descendants
+  without_taxon_id:
+    name: without_taxon_id
+    type: array
+    items:
+      type: string
+    in: query
+    minimum: 1
+    description: Exclude observations of these taxa and their descendants
   taxon_name:
     name: taxon_name
     type: array

schema/fixtures.js

@@ -70,8 +70,13 @@
           "user": { "id": 123 },
           "created_at": "2015-12-31T00:00:00",
           "private_location": "1,2",
-          "taxon": { "id": 5, "iconic_taxon_id": 1,
-            "min_species_ancestry": "1,2,3,4,5", "rank_level": 10 },
+          "taxon": {
+            "id": 5,
+            "iconic_taxon_id": 1,
+            "ancestor_ids": [1,2,3,4,5],
+            "min_species_ancestry": "1,2,3,4,5",
+            "rank_level": 10
+          },
           "project_ids": [ 543 ],
           "private_geojson": { "type": "Point", "coordinates": [ "2", "1" ] }
         },
@@ -80,7 +85,11 @@
           "user": { "id": 5 },
           "created_at": "2016-01-01T01:00:00",
           "location": "2,3",
-          "taxon": { "id": 4, "min_species_ancestry": "1,2,3,4" },
+          "taxon": {
+            "id": 4,
+            "ancestor_ids": [1,2,3,4],
+            "min_species_ancestry": "1,2,3,4"
+          },
           "non_owner_ids":[{ "user": { "id": 123 } }],
           "place_guess": "Montana",
           "private_geojson": { "type": "Point", "coordinates": [ "3", "2" ] }
@@ -98,8 +107,13 @@
           "user": { "id": 333 },
           "created_at": "1500-01-01T05:00:00",
           "observed_on": "1500-01-01T05:00:00",
-          "taxon": { "id": 123, "iconic_taxon_id": 1,
-            "min_species_ancestry": "11,22,33,123", "rank_level": 10 },
+          "taxon": {
+            "id": 123,
+            "iconic_taxon_id": 1,
+            "ancestor_ids": [11,22,33,123],
+            "min_species_ancestry": "11,22,33,123",
+            "rank_level": 10
+          },
           "sounds": {
             "id": 1,
             "license_code": "CC-BY",
@@ -110,8 +124,13 @@
         {
           "id": 5,
           "user": { "id": 333 },
-          "taxon": { "id": 123, "iconic_taxon_id": 1,
-            "min_species_ancestry": "11,22,33,123", "rank_level": 10 },
+          "taxon": {
+            "id": 123,
+            "iconic_taxon_id": 1,
+            "ancestor_ids": [11,22,33,123],
+            "min_species_ancestry": "11,22,33,123",
+            "rank_level": 10
+          },
           "private_location": "3,4",
           "private_geojson": { "type": "Point", "coordinates": [ "4", "3" ] },
           "place_guess": "Tangerina",

test/integration/v1/observations.js

@@ -74,6 +74,30 @@ describe( "Observations", function( ) {
       }).expect( 200, done );
     });
 
+    it( "finds observations by taxon_id", function( done ) {
+      request( app ).get( "/v1/observations?taxon_id=4" ).
+      expect( function( res ) {
+        expect( res.body.results.map( function( r ) { return r.id } ) ).to.contain( 1 );
+      }).expect( 200, done );
+    } );
+
+    it( "finds observations by without_taxon_id", function( done) {
+      request( app ).get( "/v1/observations?taxon_id=4&without_taxon_id=5" ).
+      expect( function( res ) {
+        expect( res.body.results.map( function( r ) { return r.id } ) ).to.contain( 2 );
+        expect( res.body.results.map( function( r ) { return r.id } ) ).not.to.contain( 1 );
+      }).expect( 200, done );
+    } );
+
+    it( "finds observations by multiple without_taxon_id", function( done) {
+      request( app ).get( "/v1/observations?without_taxon_id=4,5" ).
+      expect( function( res ) {
+        expect( res.body.results.map( function( r ) { return r.id } ) ).to.contain( 333 );
+        expect( res.body.results.map( function( r ) { return r.id } ) ).not.to.contain( 2 );
+        expect( res.body.results.map( function( r ) { return r.id } ) ).not.to.contain( 1 );
+      }).expect( 200, done );
+    } );
+
     it( "looks up projects by slug", function( done ) {
       request( app ).get( "/v1/observations?projects=a-project" ).
       expect( function( res ) {