add additional API documentation #299, #453

lib/views/swagger_v1.yml.ejs

@@ -40,6 +40,26 @@ info:
     requests will also include private information like hidden coordinates if
     the authenticated user has permission to view them.
 
+    Photos served from https://static.inaturalist.org and
+    https://inaturalist-open-data.s3.amazonaws.com have multiple size
+    variants and not all size variants are returned in responses. To access
+    other sizes, the photo URL can be modified to replace only the size
+    qualifier (each variant shares the exact same extension). The domain a photo
+    is hosted under reflects the license under which the photo is being shared,
+    and the domain may change over time if the license changes. Photos in
+    the `inaturalist-open-data` domain are shared under open licenses. These can
+    be accessed in bulk in the [iNaturalist AWS Open Dataset](
+    https://registry.opendata.aws/inaturalist-open-data/). Photos in the
+    `static.inaturalist.org` domain do not have open licenses.
+
+    The available photo sizes are:
+    * original (max 2048px in either dimension)
+    * large (max 1024px in either dimension)
+    * medium (max 500px in either dimension)
+    * small (max 240px in either dimension)
+    * thumb (max 100px in either dimension)
+    * square (75px square)
+
     iNaturalist Website: https://www.inaturalist.org/
 
     Open Source Software: https://github.com/inaturalist/

openapi/doc.js

@@ -124,6 +124,26 @@ names or a JSON string.
 To see all available fields, you can use \`fields=all\`, e.g.
 <${url}/observations?fields=all>
 
+Photos served from https://static.inaturalist.org and
+https://inaturalist-open-data.s3.amazonaws.com have multiple size
+variants and not all size variants are returned in responses. To access
+other sizes, the photo URL can be modified to replace only the size
+qualifier (each variant shares the exact same extension). The domain a photo
+is hosted under reflects the license under which the photo is being shared,
+and the domain may change over time if the license changes. Photos in
+the \`inaturalist-open-data\` domain are shared under open licenses. These can
+be accessed in bulk in the [iNaturalist AWS Open Dataset](
+https://registry.opendata.aws/inaturalist-open-data/). Photos in the
+\`static.inaturalist.org\` domain do not have open licenses.
+
+The available photo sizes are:
+* original (max 2048px in either dimension)
+* large (max 1024px in either dimension)
+* medium (max 500px in either dimension)
+* small (max 240px in either dimension)
+* thumb (max 100px in either dimension)
+* square (75px square)
+
 ## About iNaturalist
 
 [iNaturalist](https://www.inaturalist.org/) is a global community of

openapi/schema/response/common_ancestor.js

@@ -2,7 +2,14 @@ const Joi = require( "joi" );
 const taxon = require( "./taxon" );
 
 module.exports = Joi.object( ).keys( {
-  score: Joi.number( ),
+  score: Joi.number( ).min( 0 ).max( 100 ).description( `
+    Common ancestor scores are not directly comparable to the combined_score
+    of results. Generally they are similar, factoring in both vision and spatial
+    similarity, but are derived from a subset of the top results resulting in
+    a value different than combined_score. Usually the common ancestor score
+    will be above 70 as taxa need to have a high confidence in order to be
+    considered a likely common ancestor.
+  `.replace( /\s+/m, " " ) ),
   taxon: taxon.required( )
 } ).description( `
   Common ancestor taxon of some of the top results weighted by combined score.

openapi/schema/response/results_computervision.js

@@ -9,34 +9,36 @@ module.exports = Joi.object( ).keys( {
   common_ancestor: commonAncestor,
   experimental: Joi.string( ),
   results: Joi.array( ).items( Joi.object( ).keys( {
-    combined_score: Joi.number( ).required( ).description( `
+    combined_score: Joi.number( ).min( 0 ).max( 100 ).required( )
+      .description( `
       Combination of the vision and frequency scores, i.e. a score that
-      incorporates visual similarity and spatio-temporal similarity
+      incorporates visual similarity and spatial similarity
     `.replace( /\s+/m, " " ) ),
-    frequency_score: Joi.number( ).description( `
-      Score based on spatio-temporal similarity to observations of this taxon,
-      i.e. a number based on the number of Research Grade observations of this
-      taxon in the 3-degree lat/lng cell that contains this location and the 3
-      month window that contains the date. The reference values for the location
-      and date depend on what kind of record was used to generate the vision
-      results, so if it was an observation they come from the observation, but
-      if just a photo they will come from the photo's metadata. For example,
-      when generating a frequency_score for an observation observed on 1 June,
-      2020 at lat: 1, lng: 1, we would look at observations made in May, June,
-      and July and where latitude and longitude are greater than 0 or less than
-      3. 
+    frequency_score: Joi.number( ).integer( ).valid( 0, 1 ).description( `
+      This value used to be any float value between 0 and 1 reflecting a
+      measure of spatial similarity to observations of this taxon.
+      Currently frequency_score can only be 0 meaning the taxon is not expected
+      nearby, or 1 meaning the taxon is expected to be nearby. These values
+      are derived from the iNaturalist Geomodel trained on iNaturalist
+      observation locations.
     `.replace( /\s+/m, " " ) ),
-    vision_score: Joi.number( ).description( `
+    vision_score: Joi.number( ).min( 0 ).max( 100 ).description( `
       Score based on the visual similarity of the provided photo to photos of
       taxa in the computer vision model.
     `.replace( /\s+/m, " " ) ),
     taxon: taxon.required( )
   } ) ).required( ).description( `
     Scores are provided without units and are intended for sorting the
     suggestions. One type of score is not necessarily comparable to another,
-    e.g. a taxon with a frequency_score of 3 should not necessarily be shown
-    before one with a vision_score of 1. None of the scores are probabilities of
-    accuracy or measures of confidence.
+    e.g. a taxon with a vision_score of 30 should not necessarily be shown
+    before one with a frequency_score of 1. None of the scores are probabilities of
+    accuracy or measures of confidence. Score ranges will vary from
+    observation to observation (e.g. a result with combined_score of 80 for one
+    observation is not equally as likely a result with the same score for a
+    different observation). Within results for a single observation, scores
+    reflect relative confidence. In a single response, a result with a combined
+    score twice another result is more likely to be accurate, but not exactly
+    twice as likely.
   `.replace( /\s+/m, " " ) )
 } ).unknown( false )
   .meta( { unpublished: true } );