swagger_v1.yml.ejs

swagger: "2.0"
info:
  title: iNaturalist API
  description: |
    # https://api.inaturalist.org/v1/

    [iNaturalist](https://www.inaturalist.org/) is a global community of
    naturalists, scientists, and members of the public sharing over a million
    wildlife sightings to teach one another about the natural world while
    creating high quality citizen science data for science and conservation.

    These API methods return data in JSON/JSONP and PNG response formats. They
    are meant to supplement the existing [iNaturalist
    API](https://www.inaturalist.org/pages/api+reference), implemented in Ruby
    on Rails, which has more functionality and supports more write operations,
    but tends to be slower and have less consistent response formats. Visit our
    [developers page](https://www.inaturalist.org/pages/developers) for more
    information. Write operations that expect and return JSON describe a single
    `body` parameter that represents the request body, which should be specified
    as JSON. See the "Model" of each body parameter for attributes that we
    accept in these JSON objects.

    Multiple values for a single URL 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
    parameters of the observation search APIs, and will generate map tiles
    reflecting the same observations returned by searches. These
    "Observation Tile" methods have corresponding
    [UTFGrid](https://github.com/mapbox/utfgrid-spec) JSON
    responses which return information needed to make interactive maps.

    Authentication in the Node API is handled via JSON Web Tokens (JWT). To
    obtain one, make an [OAuth-authenticated
    request](http://www.inaturalist.org/pages/api+reference#auth) to
    https://www.inaturalist.org/users/api_token. Each JWT will expire after 24
    hours. Authentication required for all PUT and POST requests. Some GET
    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/

    ## Terms of Use

    Use of this API is subject to the iNaturalist
    [Terms of Service](https://www.inaturalist.org/terms) and
    [Privacy Policy](https://www.inaturalist.org/privacy). We will block any
    use of our API that violates our Terms or Privacy Policy without notice.
    The API is intended to support application development, not data scraping.
    For pre- generated data exports, see
    https://www.inaturalist.org/pages/developers.

    Please note that we throttle API usage to a max of 100 requests per minute,
    though we ask that you try to keep it to 60 requests per minute or lower,
    and to keep under 10,000 requests per day. If we notice usage that has
    serious impact on our performance we may institute blocks without
    notification.

    Terms of Service: https://www.inaturalist.org/terms

    Privacy Policy: https://www.inaturalist.org/privacy
  version: "1.3.0"
schemes:
  - http
  - https
basePath: /v1
produces:
  - application/json
tags:
  - name: Annotations
    description: Create, delete, and vote
  - name: Comments
    description: Create, update, and delete
  - name: Controlled Terms
    description: Search and fetch
  - name: Flags
    description: Create, update, and delete flags
  - name: Identifications
    description: Create, update, and delete
  - name: Messages
    description: Create, fetch, delete
  - name: Observation Field Values
    description: Create, update, and delete
  - name: Observation Photos
    description: Create and delete
  - name: Observations
    description: CRUD, search, faving, quality metrics, stats, and more
  - name: Places
    description: Search and fetch
  - name: Posts
    description: Fetch site and project posts
  - name: Project Observations
    description: Create, update, and delete
  - name: Projects
    description: Search and fetch projects and members
  - name: Search
    description: Site search
  - name: Taxa
    description: Search and fetch
  - name: Users
    description: Fetch and update
  - name: Observation Tiles
    description: Map observation search results
  - name: Polygon Tiles
    description: Place geometry and taxon range tiles
  - name: UTFGrid
    description: JSON for observation tiles
paths:
  /annotations:
    post:
      summary: Annotation Create
      description: |
        Create an annotation
      consumes:
       - application/json
      parameters:
        - name: body
          in: body
          description: Annotation object
          schema:
            $ref: "#/definitions/PostAnnotation"
      tags:
        - Annotations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /annotations/{id}:
    delete:
      summary: Annotation Delete
      description: |
        Delete an annotation
      parameters:
        - $ref: "#/parameters/annotation_path_id"
      tags:
        - Annotations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /votes/vote/annotation/{id}:
    post:
      summary: Annotation Vote
      description: |
        Vote on an annotation
      parameters:
        - $ref: "#/parameters/annotation_path_id"
        - name: body
          in: body
          description: Vote object
          schema:
            $ref: "#/definitions/PostVote"
      tags:
        - Annotations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /votes/unvote/annotation/{id}:
    delete:
      summary: Annotation Unvote
      description: |
        Remove a vote from annotation
      parameters:
        - $ref: "#/parameters/annotation_path_id"
      tags:
        - Annotations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /comments:
    post:
      summary: Comment Create
      description: |
        Create a comment
      consumes:
       - application/json
      parameters:
        - name: body
          in: body
          description: Comment object
          schema:
            $ref: "#/definitions/PostComment"
      tags:
        - Comments
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /comments/{id}:
    put:
      summary: Comment Update
      description: |
        Update a comment
      consumes:
       - application/json
      parameters:
        - $ref: "#/parameters/path_id"
        - name: body
          in: body
          description: Comment object
          schema:
            $ref: "#/definitions/PostComment"
      tags:
        - Comments
      security:
        - api_token: []
      responses:
        200:
          description: OK
    delete:
      summary: Comment Delete
      description: |
        Delete a comment
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Comments
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /controlled_terms:
    get:
      summary: Terms Index
      description: |
        List all attribute controlled terms
      tags:
        - Controlled Terms
      responses:
        200:
          description: OK
  /controlled_terms/for_taxon:
    get:
      summary: Terms for Taxon
      description: |
        Returns attribute controlled terms relevant to a taxon
      parameters:
        - name: taxon_id
          type: integer
          in: query
          minimum: 1
          description: Filter by this taxon
          required: true
      tags:
        - Controlled Terms
      responses:
        200:
          description: OK
  /flags:
    post:
      summary: Flag Create
      description: |
        Create a flag. To create a custom flag beyond the standard `spam` and
        `inappropriate` flags, set `flag` to `other` and include a `flag_explanation`
      consumes:
       - application/json
      parameters:
        - name: body
          in: body
          description: Flag object
          schema:
            $ref: "#/definitions/PostFlag"
      tags:
        - Flags
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /flags/{id}:
    put:
      summary: Flag Update
      description: |
        Update a flag. Generally only used to resolve the flag.
      parameters:
        - $ref: "#/parameters/path_id"
        - name: body
          in: body
          schema:
            $ref: "#/definitions/PutFlag"
      tags:
        - Flags
      security:
        - api_token: []
      responses:
        200:
          description: OK
    delete:
      summary: Flag Delete
      description: |
        Delete a flag
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Flags
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /identifications/{id}:
    get:
      summary: Identification Details
      description: |
        Given an ID, or an array of IDs in comma-delimited format, returns
        corresponding identifications. A maximum of 30 results will be returned
      consumes:
       - application/json
      parameters:
        - $ref: "#/parameters/path_multi_id"
      tags:
        - Identifications
      responses:
        200:
          description: OK
    put:
      summary: Identification Update
      description: |
        Update an identification. Note that to "withdraw" an observation you
        send a `PUT` request to this endpoint and set the `current`
        attribute to false. To "restore" it you do the same but set
        `current` to `true`. Only one identification by a given user can be
        `current` for a given observation, so if you "restore" one all the other
        identifications by the authenticated user for the given observation will
        be withdrawn.
      consumes:
       - application/json
      parameters:
        - $ref: "#/parameters/path_id"
        - name: body
          in: body
          description: Identification object
          schema:
            $ref: "#/definitions/PostIdentification"
      tags:
        - Identifications
      security:
        - api_token: []
      responses:
        200:
          description: OK
    delete:
      summary: Identification Delete
      description: |
        Delete an identification. See description of `PUT /identifications/{id}
        for notes on withdrawing and restoring identifications.
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Identifications
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /identifications:
    post:
      summary: Identification Create
      description: Create an identification
      consumes:
       - application/json
      parameters:
        - name: body
          in: body
          description: Identification object
          schema:
            $ref: "#/definitions/PostIdentification"
      tags:
        - Identifications
      security:
        - api_token: []
      responses:
        200:
          description: OK
    get:
      summary: Identification Search
      description: |
        Given zero to many of following parameters, returns identifications
        matching the search criteria
      parameters:
        <%- include( "_identification_search_params_v1.yml.ejs", { type: "index" } ) %>
      tags:
        - Identifications
      responses:
        200:
          description: OK
  /identifications/categories:
    get:
      summary: Identification Categories
      description: |
        Given zero to many of following parameters, return counts of the
        categories of identifications matching the search criteria
      parameters:
        <%- include( "_identification_search_params_v1.yml.ejs", { type: "index" } ) %>
      tags:
        - Identifications
      responses:
        200:
          description: OK
  /identifications/species_counts:
    get:
      summary: Identification Species Counts
      description: |
        Given zero to many of following parameters, returns `leaf taxa`
        associated with identifications matching the search criteria and the
        count of identifications they are associated with, ordered by count
        descending. `Leaf taxa` are the leaves of the taxonomic tree containing
        only the taxa associated with observations matching the search criteria.
      parameters:
        <%- include( "_identification_search_params_v1.yml.ejs", { type: "index" } ) %>
        - name: taxon_of
          type: string
          in: query
          description: Source of the taxon for counting
          enum:
            - identification
            - observation
          default: identification
        - name: order
          type: string
          in: query
          description: Sort order
          default: desc
          enum:
            - desc
            - asc
      tags:
        - Identifications
      responses:
        200:
          description: |
            Returns an object with metadata and an array of taxa
          schema:
            $ref: "#/definitions/SpeciesCountsResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /identifications/identifiers:
    get:
      summary: Identification Identifiers
      description: |
        Given zero to many of following parameters, returns creators of
        identifications matching the search criteria and the count of
        matching identifications, ordered by count descending. A
        maximum of 500 results will be returned
      parameters:
        <%- include( "_identification_search_params_v1.yml.ejs", { type: "index" } ) %>
      tags:
        - Identifications
      responses:
        200:
          description: |
            Returns an object with metadata and an array of identifiers
          schema:
            $ref: "#/definitions/UserCountsResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /identifications/observers:
    get:
      summary: Identification Observers
      description: |
        Given zero to many of following parameters, returns creators of
        observations of identifications matching the search criteria and
        the count of matching observations, ordered by count descending
      parameters:
        <%- include( "_identification_search_params_v1.yml.ejs", { type: "index" } ) %>
      tags:
        - Identifications
      responses:
        200:
          description: |
            Returns an object with metadata and an array of observers
          schema:
            $ref: "#/definitions/UserCountsResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /identifications/recent_taxa:
    get:
      summary: Identification Recent Taxa
      description: |
        Returns an array of objects each containing an identification and a
        taxon. Returns IDs representing the earliest occurrence of taxa
        associated with identifications in the filtered set of results
      parameters:
        <%- include( "_identification_search_params_v1.yml.ejs", { type: "index" } ) %>
      tags:
        - Identifications
      responses:
        200:
          description: OK
  /identifications/similar_species:
    get:
      summary: Identification Similar Species
      description: |
        Returns species attached to IDs of observations of this taxon, or
        attached to observations identified as this species, ordered by combined
        frequency descending. This will only return species in the same iconic
        taxon, and will never return descendants of the chosen taxon
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "similar" } ) %>
        - name: taxon_id
          type: integer
          in: query
          minimum: 1
          description: Only show observations of these taxa and their descendants
          required: true
      tags:
        - Identifications
      responses:
        200:
          description: OK
  /messages:
    get:
      summary: Retrieve messages for the authenticated user. This does not mark them as read.
      description:
        Show the user's inbox or sent box
      parameters:
        - $ref: "#/parameters/page"
        - name: box
          in: query
          type: string
          description: Whether to view messages the user has received (default) or messages the user has sent
          default: inbox
          enum: [inbox, sent, any]
        - name: q
          in: query
          type: string
          description: Search query for subject and body
        - name: user_id
          in: query
          type: string
          description: User ID or username of correspondent to filter by
        - name: threads
          in: query
          type: boolean
          default: false
          description: |
            Groups results by `thread_id`, only shows the latest message per
            thread, and includes a `thread_messages_count` attribute showing the
            total number of messages in that thread. Note that this will not
            work with the `q` param, and it probably should only be used with
            `box=any` because the `thread_messages_count` will be inaccurate when
            you restrict it to `inbox` or `sent`.
      tags:
        - Messages
      security:
        - api_token: []
      responses:
        200:
          description: OK
        default:
          description: |
            Returns an object with metadata and an array of messages
          schema:
            $ref: "#/definitions/MessagesResponse"
    post:
      summary: Create a new message
      description: Create and deliver a new message to another user
      tags:
        - Messages
      security:
        - api_token: []
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/PostMessage"
      responses:
        200:
          description: |
            Returns the message just created
          schema:
            $ref: "#/definitions/Message"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /messages/{id}:
    get:
      summary: Retrieve messages in a thread
      description: |
        Retrieves all messages in the thread the specified message belongs to
        and marks them all as read.
      tags:
        - Messages
      security:
        - api_token: []
      parameters:
        - $ref: "#/parameters/path_id"
      responses:
        200:
          description: |
            Returns an object with metadata and an array of messages
          schema:
            properties:
              reply_to_user:
                description: User to reply to
                $ref: "#/definitions/User"
              thread_id:
                description: Identifier for this thread
                type: integer
              flaggable_message_id:
                description: |
                  Identifier for the message that should be flagged if the user
                  chooses to flag this thread
                type: integer
              results:
                type: array
                items:
                  $ref: "#/definitions/Message"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    delete:
      summary: Delete a message / thread
      description: |
        This will all of the authenticated user's copies of the messages in tha
        thread to which the specified message belongs.
      tags:
        - Messages
      security:
        - api_token: []
      parameters:
        - $ref: "#/parameters/path_id"
      responses:
        200:
          description: |
            No return data, 200 just means deletion was successful
        404:
          description: |
            Specified message doesn't exist
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /messages/unread:
    get:
      summary: Gets a count of messages the authenticated user has not read
      summary: Simple response to get the unread messages count
      tags:
        - Messages
      security:
        - api_token: []
      responses:
        200:
          description: Number of unread messages
          schema:
            properties:
              count:
                type: integer
                description: Number of unread messages
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /observations/{id}:
    get:
      summary: Observation Details
      description: |
        Given an ID, or an array of IDs in comma-delimited format, returns
        corresponding observations. A maximum of 200 results will be returned
      parameters:
        - $ref: "#/parameters/path_multi_id"
      tags:
        - Observations
      responses:
        200:
          description: |
            Returns an object with metadata and an array of observations
          schema:
            $ref: "#/definitions/ObservationsShowResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    put:
      summary: Observation Update
      description: |
        Update an observation
      consumes:
       - application/json
      parameters:
        - $ref: "#/parameters/path_id"
        - name: body
          in: body
          description: Comment object
          schema:
            $ref: "#/definitions/PostObservation"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
    delete:
      summary: Observation Delete
      description: |
        Delete an observation
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observations/{id}/fave:
    post:
      summary: Observations Fave
      description: |
        Fave an observation
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observations/{id}/unfave:
    delete:
      summary: Observations Unfave
      description: |
        Unfave an observation
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observations/{id}/review:
    post:
      summary: Observations Review
      description: |
        Review an observation
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observations/{id}/unreview:
    post:
      summary: Observations Unreview
      description: |
        Unreview an observation
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observations/{id}/subscriptions:
    get:
      summary: Observation Subscriptions
      description: |
        Fetches any subscriptions the current user has to this observation
        or the observer
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observations/{id}/quality/{metric}:
    post:
      summary: Quality Metric Set
      description: |
        Set the value of a quality metric
      parameters:
        - $ref: "#/parameters/path_id"
        - $ref: "#/parameters/path_metric"
        - name: body
          in: body
          description: Quality object
          schema:
            $ref: "#/definitions/PostQuality"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
    delete:
      summary: Quality Metric Delete
      description: |
        Delete a quality metric
      consumes:
       - application/x-www-form-urlencoded
      parameters:
        - $ref: "#/parameters/path_id"
        - $ref: "#/parameters/path_metric"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observations/{id}/taxon_summary:
    get:
      summary: Observation Taxon Summary
      description: |
        Fetches information about this observation's taxon, within the context
        of this observation's location
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Observations
      responses:
        200:
          description: OK
  /subscriptions/observation/{id}/subscribe:
    post:
      summary: Observation Subscribe
      description: |
        Toggles current user's subscription to this observation. If the logged-in
        user is not subscribed, POSTing here will subscribe them. If they are already
        subscribed, this will remove the subscription
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /votes/vote/observation/{id}:
    post:
      summary: Observation Vote
      description: |
        Vote on an observation. A vote with an empty `scope` is recorded as a
        `fave` of the observation. A vote with scope `needs_id` is recorded as a
        vote on the Quality Grade criterion "can the Community ID still be
        confirmed or improved?", and can be an up or down vote
      parameters:
        - $ref: "#/parameters/path_id"
        - name: body
          in: body
          description: Vote object
          schema:
            $ref: "#/definitions/PostObservationVote"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /votes/unvote/observation/{id}:
    delete:
      summary: Observation Unvote
      description: Remove a vote from an observation
      parameters:
        - $ref: "#/parameters/path_id"
        - name: body
          in: body
          description: Vote object
          schema:
            $ref: "#/definitions/PostObservationVote"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observations:
    get:
      summary: Observation Search
      description: |
        Given zero to many of following parameters, returns observations
        matching the search criteria. The large size of the observations index
        prevents us from supporting the `page` parameter when retrieving records
        from large result sets. If you need to retrieve large numbers of
        records, use the `per_page` and `id_above` or `id_below` parameters
        instead.
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "index" } ) %>
      tags:
        - Observations
      responses:
        200:
          description: |
            Returns an object with metadata and an array of observations
          schema:
            $ref: "#/definitions/ObservationsResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    post:
      summary: Observation Create
      description: |
        Create an observation
      consumes:
       - application/json
      parameters:
        - name: body
          in: body
          description: Comment object
          schema:
            $ref: "#/definitions/PostObservation"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observations/deleted:
    get:
      summary: Observations Deleted
      description: |
        Given a starting date, return an array of IDs of the authenticated
        user's observations that have been deleted since that date. Requires
        authentication
      parameters:
        - $ref: "#/parameters/since"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observations/histogram:
    get:
      summary: Observation Histogram
      description: |
        Given zero to many of following parameters, returns histogram data about
        observations matching the search criteria
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "search" } ) %>
        - $ref: "#/parameters/date_field"
        - $ref: "#/parameters/interval"
      tags:
        - Observations
      responses:
        200:
          description: |
            Returns an object with metadata and an array of histogram data
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /observations/identifiers:
    get:
      summary: Observation Identifiers
      description: |
        Given zero to many of following parameters, returns identifiers of
        observations matching the search criteria and the count of
        observations they have identified, ordered by count descending. A
        maximum of 500 results will be returned
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "search" } ) %>
      tags:
        - Observations
      responses:
        200:
          description: |
            Returns an object with metadata and an array of identifiers
          schema:
            $ref: "#/definitions/UserCountsResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /observations/observers:
    get:
      summary: Observation Observers
      description: |
        Given zero to many of following parameters, returns observers of
        observations matching the search criteria and the count of
        observations and distinct taxa of rank `species` they have observed. A
        maximum of 500 results will be returned
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "search" } ) %>
      tags:
        - Observations
      responses:
        200:
          description: |
            Returns an object with metadata and an array of observers
          schema:
            $ref: "#/definitions/ObservationsObserversResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /observations/places_counts:
    get:
      summary: Observation Place Counts
      description: |
        Given zero to many of the following parameters, returns the number of observations matching
        the search criteria, grouped by place. Each result includes the place and the count of 
        associated observations. This endpoint works similarly to `/observations`, but instead of 
        returning individual observations, it returns aggregated results per place. A
        maximum of 1000 results will be returned
      parameters:
      <%- include( "_observation_search_params_v1.yml.ejs", { type: "index" } ) %>
      tags:
        - Observations
      responses:
        200:
          description: |
            Returns an object with metadata and an array of taxa
          schema:
            $ref: "#/definitions/PlacesCountsResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /observations/popular_field_values:
    get:
      summary: Observation Popular Field Values
      description: |
        Given zero to many of following parameters, returns an array of
        relevant controlled terms values and a monthly histogram
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "search" } ) %>
      tags:
        - Observations
      responses:
        200:
          description: OK
  /observations/species_counts:
    get:
      summary: Observation Species Counts
      description: |
        Given zero to many of following parameters, returns `leaf taxa`
        associated with observations matching the search criteria and the count of
        observations they are associated with, ordered by count descending.
        `Leaf taxa` are the leaves of the taxonomic tree containing only the
        taxa associated with observations matching the search criteria.
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "search" } ) %>
        - $ref: "#/parameters/include_ancestors"
        - $ref: "#/parameters/page"
        - $ref: "#/parameters/per_page_species_counts"
      tags:
        - Observations
      responses:
        200:
          description: |
            Returns an object with metadata and an array of taxa
          schema:
            $ref: "#/definitions/SpeciesCountsResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /observations/updates:
    get:
      summary: Observation User Updates
      description: |
        Given zero to many of following parameters, returns an array of objects
        representing new comments and identifications on observations the authenticated
        user has subscribed to. Requires authentication
      parameters:
        - $ref: "#/parameters/created_after"
        - $ref: "#/parameters/viewed"
        - $ref: "#/parameters/observations_by"
        - $ref: "#/parameters/page"
        - $ref: "#/parameters/per_page"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observations/{id}/viewed_updates:
    put:
      summary: Observation Field Value Update
      description: |
        Mark all updates associated with this observation as viewed by logged-in user
      consumes:
       - application/json
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observation_field_values/{id}:
    put:
      summary: Observation Field Value Update
      description: |
        Update an observation field value
      consumes:
       - application/json
      parameters:
        - $ref: "#/parameters/path_id"
        - name: body
          in: body
          description: Observation field value object
          schema:
            $ref: "#/definitions/PostObservationFieldValue"
      tags:
        - Observation Field Values
      security:
        - api_token: []
      responses:
        200:
          description: OK
    delete:
      summary: Observation Field Value Delete
      description: |
        Delete an observation field value
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Observation Field Values
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observation_field_values:
    post:
      summary: Observation Field Value Create
      description: |
        Create an observation field value
      consumes:
       - application/json
      parameters:
        - name: body
          in: body
          description: Observation field value object
          schema:
            $ref: "#/definitions/PostObservationFieldValue"
      tags:
        - Observation Field Values
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observation_photos/{id}:
    put:
      summary: Observation Photo Update
      description: Update an observation photo
      consumes:
        - multipart/form-data
      parameters:
        - $ref: "#/parameters/path_id"
        - name: observation_photo[position]
          in: formData
          description: Position in which the photo is displayed for the observation
          type: integer
        - name: file
          in: formData
          description: The photo
          type: file
      tags:
        - Observation Photos
      security:
        - api_token: []
      responses:
        200:
          description: OK
    delete:
      summary: Observation Photo Delete
      description: |
        Delete an observation photo
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Observation Photos
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /observation_photos:
    post:
      summary: Observation Photo Create
      description: |
        Create an observation photo
      consumes:
        - multipart/form-data
      parameters:
        - name: observation_photo[observation_id]
          in: formData
          description: Observation ID
          type: integer
        - name: observation_photo[uuid]
          in: formData
          description: Observation UUID
          type: string
        - name: file
          in: formData
          description: The photo
          type: file
      tags:
        - Observation Photos
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /photos:
    post:
      summary: Photo Create
      description: |
        Create a photo
      consumes:
        - multipart/form-data
      parameters:
        - name: file
          in: formData
          description: The photo
          type: file
      tags:
        - Photos
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /places/{id}:
    get:
      summary: Place Details
      description: |
        Given an ID, or an array of IDs in comma-delimited format, returns
        corresponding places. A maximum of 500 results will be returned
      parameters:
        - $ref: "#/parameters/path_multi_id_or_slug"
        - name: admin_level
          in: query
          type: array
          enum:
            - -10
            - 0
            - 10
            - 20
            - 30
            - 100
          items:
            type: integer
          description: Admin level of a place, or an array of admin levels
            in comma-delimited format. Supported admin levels are: -10
            (continent), 0 (country), 10 (state), 20 (county), 30 (town),
            100 (park)
      tags:
        - Places
      responses:
        200:
          description: |
            Returns an object with metadata and an results array of places
          schema:
            $ref: "#/definitions/PlacesResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /places/autocomplete:
    get:
      summary: Place Autocomplete
      description: |
        Given an string, returns places with names starting with the search
        term.
      parameters:
        - $ref: "#/parameters/autocomplete_q"
        - name: order_by
          type: string
          in: query
          description: Sort field
          enum:
            - area
      tags:
        - Places
      responses:
        200:
          description: |
            Returns an object with metadata and an results array of places
          schema:
            $ref: "#/definitions/PlacesResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /places/nearby:
    get:
      summary: Nearby Places
      description: |
        Given an bounding box, and an optional name query, return `standard`
        iNaturalist curator approved and `community` non-curated places nearby
      parameters:
        - $ref: "#/parameters/nelat_required"
        - $ref: "#/parameters/nelng_required"
        - $ref: "#/parameters/swlat_required"
        - $ref: "#/parameters/swlng_required"
        - name: name
          in: query
          type: string
          description: Name must match this value
        - $ref: "#/parameters/per_page"
      tags:
        - Places
      responses:
        200:
          description: |
            Returns an object with metadata and an results object containing
            `standard` and `community` places
          schema:
            $ref: "#/definitions/NearbyPlacesResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /posts:
    get:
      summary: Posts Search
      description: |
        Return journal posts from the iNaturalist site
      parameters:
        - $ref: "#/parameters/posts_login"
        - $ref: "#/parameters/posts_project_id"
        - $ref: "#/parameters/page"
        - $ref: "#/parameters/per_page"
      tags:
        - Posts
      security:
        - api_token: []
      responses:
        200:
          description: OK
    post:
      summary: Post Create
      description: |
        Create a post
      consumes:
       - application/json
      parameters:
        - name: body
          in: body
          description: Post object
          schema:
            $ref: "#/definitions/PostPost"
      tags:
        - Posts
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /posts/{id}:
    put:
      summary: Post Update
      description: |
        Update a post
      consumes:
       - application/json
      parameters:
        - $ref: "#/parameters/path_id"
        - name: body
          in: body
          description: Post object
          schema:
            $ref: "#/definitions/PostPost"
      tags:
        - Posts
      security:
        - api_token: []
      responses:
        200:
          description: OK
    delete:
      summary: Post Delete
      description: |
        Delete a post
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Posts
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /posts/for_user:
    get:
      summary: Posts For User
      description: |
        Return journal posts from the iNaturalist site. If the user is logged-in,
        also return posts from projects the user is subscribed to
      parameters:
        - name: newer_than
          type: string
          format: date-time
          in: query
          description: returns posts newer than the post with this ID
        - name: older_than
          type: string
          format: date-time
          in: query
          description: returns posts older than the post with this ID
        - $ref: "#/parameters/page"
      tags:
        - Posts
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /project_observations/{id}:
    put:
      summary: Project Observation Update
      description: Update a project observation
      consumes:
       - application/json
      parameters:
        - $ref: "#/parameters/path_id"
        - name: body
          in: body
          description: Comment object
          schema:
            $ref: "#/definitions/UpdateProjectObservation"
      tags:
        - Project Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
    delete:
      summary: Project Observation Delete
      description: Delete a project observation
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Project Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /project_observations:
    post:
      summary: Project Observation Create
      description: Add an observation to a project
      consumes:
       - application/json
      parameters:
        - name: body
          in: body
          description: ProjectObservation object
          schema:
            $ref: "#/definitions/PostProjectObservation"
      tags:
        - Project Observations
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /projects:
    get:
      summary: Project Search
      description: |
        Given zero to many of following parameters, returns projects
        matching the search criteria
      parameters:
        <%- include( "_project_search_params_v1.yml.ejs" ) %>
      tags:
        - Projects
      responses:
        200:
          description: |
            Returns an object with metadata and an array of projects
          schema:
            $ref: "#/definitions/ProjectsResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /projects/{id}:
    get:
      summary: Project Details
      description: |
        Given an ID, or an array of IDs in comma-delimited format, returns
        corresponding projects. A maximum of 100 results will be returned
      parameters:
        - $ref: "#/parameters/path_multi_id_or_slug"
        - $ref: "#/parameters/rule_details"
      tags:
        - Projects
      responses:
        200:
          description: |
            Returns an object with metadata and an array of projects
          schema:
            $ref: "#/definitions/ProjectsResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /projects/{id}/join:
    post:
      summary: Projects Join
      description: |
        Join a project
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Projects
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /projects/{id}/leave:
    delete:
      summary: Projects Leave
      description: |
        Leave a project
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Projects
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /projects/{id}/members:
    get:
      summary: Project Members
      description: |
        Given an ID, return members of the project
      parameters:
        - $ref: "#/parameters/path_id"
        - name: role
          type: string
          in: query
          description: Membership role
          enum:
            - curator
            - manager
        - $ref: "#/parameters/skip_counts"
        - $ref: "#/parameters/page"
        - $ref: "#/parameters/per_page"
      tags:
        - Projects
      responses:
        200:
          description: |
            Returns an object with metadata and an results array of projects
          schema:
            $ref: "#/definitions/ProjectMembersResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /projects/{id}/membership:
    get:
      summary: Membership of current user
      description: |
        Given an ID, or an array of IDs in comma-delimited format, return the details of the
        authenticated user's membership in these projects
      parameters:
        - $ref: "#/parameters/path_multi_id"
      tags:
        - Projects
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /projects/{id}/subscriptions:
    get:
      deprecated: true
      summary: Project Subscriptions
      description: |
        [Deprecated] Subscriptions to projects are managed through joining and
        leaving projects, so this will not return any useful information.

        Given an ID, return subscription of the current user
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Projects
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /projects/{id}/add:
    post:
      summary: Project Add
      description: Add an observation to a project
      consumes:
       - application/json
      parameters:
        - $ref: "#/parameters/path_id"
        - name: body
          in: body
          description: ProjectObservation object
          schema:
            $ref: "#/definitions/PostProjectAdd"
      tags:
        - Projects
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /projects/{id}/remove:
    delete:
      summary: Project Add
      description: Remove an observation from a project
      consumes:
       - application/json
      parameters:
        - $ref: "#/parameters/path_id"
        - name: body
          in: body
          description: ProjectObservation object
          schema:
            $ref: "#/definitions/PostProjectAdd"
      tags:
        - Projects
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /projects/autocomplete:
    get:
      summary: Project Autocomplete
      description: |
        Given an string, returns projects with titles starting with the search term
      parameters:
        <%- include( "_project_search_params_v1.yml.ejs", { type: "autocomplete" } ) %>
      tags:
        - Projects
      responses:
        200:
          description: |
            Returns an object with metadata and an results array of places
          schema:
            $ref: "#/definitions/ProjectsResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /search:
    get:
      summary: Site Search
      description: |
        Given zero to many of following parameters, returns object matching the search criteria
      parameters:
        - $ref: "#/parameters/search_q"
        - $ref: "#/parameters/sources"
        - $ref: "#/parameters/associated_place_id"
        - $ref: "#/parameters/include_taxon_ancestors"
        - $ref: "#/parameters/per_page"
        - $ref: "#/parameters/locale"
        - $ref: "#/parameters/preferred_place_id"
      tags:
        - Search
      responses:
        200:
          description: OK
  /subscriptions/project/{id}/subscribe:
    post:
      summary: Project Subscribe
      description: |
        Toggles current user's subscription to this project. If the logged-in
        user is not subscribed, POSTing here will subscribe them. If they are already
        subscribed, this will remove the subscription
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Projects
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /taxa/{id}:
    get:
      summary: Taxon Details
      description: |
        Given an ID, or an array of IDs in comma-delimited format, returns
        corresponding taxa. A maximum of 30 results will be returned
      parameters:
        - $ref: "#/parameters/path_multi_id"
        - $ref: "#/parameters/rank_level"
      tags:
        - Taxa
      responses:
        200:
          description: |
            Returns an object with metadata and a results array of taxa
          schema:
            $ref: "#/definitions/TaxaShowResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /taxa:
    get:
      summary: Taxon Search
      description: |
        Given zero to many of following parameters, returns taxa matching the search criteria
      parameters:
        - $ref: "#/parameters/autocomplete_q_not_required"
        - name: is_active
          type: boolean
          in: query
          description: Taxon is `active`
        - $ref: "#/parameters/taxa_taxon_id"
        - $ref: "#/parameters/parent_id"
        - $ref: "#/parameters/rank"
        - $ref: "#/parameters/rank_level"
        - $ref: "#/parameters/id_above"
        - $ref: "#/parameters/id_below"
        - $ref: "#/parameters/per_page"
        - $ref: "#/parameters/locale"
        - $ref: "#/parameters/preferred_place_id"
        - $ref: "#/parameters/only_id"
        - $ref: "#/parameters/all_names"
        - $ref: "#/parameters/order"
        - $ref: "#/parameters/taxa_order_by"
      tags:
        - Taxa
      responses:
        200:
          description: |
            Returns an object with search metadata and a results array of taxa
          schema:
            $ref: "#/definitions/TaxaShowResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /taxa/autocomplete:
    get:
      summary: Taxon Autocomplete
      description: |
        Given an string, returns taxa with names starting with the search term
      parameters:
        - $ref: "#/parameters/autocomplete_q"
        - name: is_active
          type: boolean
          in: query
          description: Taxon is `active`
        - $ref: "#/parameters/taxa_taxon_id"
        - $ref: "#/parameters/rank"
        - $ref: "#/parameters/rank_level"
        - name: per_page
          type: string
          in: query
          description: Number of results to return in a `page`. The maximum value is 30 for this endpoint
        - $ref: "#/parameters/locale"
        - $ref: "#/parameters/preferred_place_id"
        - $ref: "#/parameters/all_names"
      tags:
        - Taxa
      responses:
        200:
          description: |
            Returns an object with search metadata and a results array of taxa
          schema:
            $ref: "#/definitions/TaxaAutocompleteResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /users/{id}:
    get:
      summary: User Details
      description: Given an ID, returns corresponding user
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Users
      responses:
        200:
          description: OK
    put:
      summary: User Update
      description: |
        Update a user
      consumes:
       - application/json
      parameters:
        - $ref: "#/parameters/path_id"
      tags:
        - Users
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /users/{id}/projects:
    get:
      summary: User Projects
      description: |
        Return projects as user has joined / followed
      parameters:
        - $ref: "#/parameters/path_id"
        - $ref: "#/parameters/rule_details"
        - $ref: "#/parameters/project_type"
        - $ref: "#/parameters/page"
        - $ref: "#/parameters/per_page"
      tags:
        - Users
      responses:
        200:
          description: OK
  /users/autocomplete:
    get:
      summary: User Autocomplete
      description: |
        Given an string, returns users with names or logins starting with the search term
      parameters:
        - $ref: "#/parameters/autocomplete_q"
        - $ref: "#/parameters/autocomplete_project_id"
        - $ref: "#/parameters/per_page"
      tags:
        - Users
      responses:
        200:
          description: OK
  /users/me:
    get:
      summary: Users Me
      description: Fetch the logged-in user
      tags:
        - Users
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /users/{id}/mute:
    post:
      summary: Mute a User
      description: |
        Make it so the authenticated user stops receiving notifications about
        activity by the user specified by {id}.
      tags:
        - Users
      security:
        - api_token: []
      parameters:
        - $ref: "#/parameters/path_id"
      responses:
        200:
          description: Returns an empty 200 response on success
        404:
          description: Specified user does not exist
    delete:
      summary: Unmute a User
      description: Remove a mute on the user specified by {id}
      tags:
        - Users
      security:
        - api_token: []
      parameters:
        - $ref: "#/parameters/path_id"
      responses:
        200:
          description: Returns an empty 200 response on success
        404:
          description: Specified user does not exist
  /users/resend_confirmation:
    post:
      summary: User Resend Confirmation
      description: Resend an email confirmation
      consumes:
       - application/json
      tags:
        - Users
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /users/update_session:
    put:
      summary: User Update Session
      description: Update the logged-in user's session
      consumes:
       - application/json
      parameters:
        - name: body
          in: body
          description: Comment object
          schema:
            $ref: "#/definitions/PostUserUpdateSession"
      tags:
        - Users
      security:
        - api_token: []
      responses:
        200:
          description: OK
  /colored_heatmap/{zoom}/{x}/{y}.png:
    get:
      summary: Colored Heatmap Tiles
      description: |
        Given zero to many of following parameters, returns a PNG image
        representing the matching observations within a map tile, following
        the XYZ tiling scheme
      produces:
        - image/png
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "tiles" } ) %>
      tags:
        - Observation Tiles
      responses:
        200:
          description: |
            Returns a PNG map tile image
  /colored_heatmap/{zoom}/{x}/{y}.grid.json:
    get:
      summary: Colored Heatmap Tiles UTFGrid
      description: |
        Given zero to many of following parameters, returns a JSON file
        following the UTFGrid spec, representing observations matching
        the search criteria
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "tiles" } ) %>
      tags:
        - UTFGrid
      responses:
        200:
          description: |
            Returns a UTFGrid
          schema:
            $ref: "#/definitions/UTFGridResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /grid/{zoom}/{x}/{y}.png:
    get:
      summary: Grid Tiles
      description: |
        Given zero to many of following parameters, returns a PNG image
        representing the matching observations within a map tile, following
        the XYZ tiling scheme
      produces:
        - image/png
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "tiles" } ) %>
      tags:
        - Observation Tiles
      responses:
        200:
          description: |
            Returns a PNG map tile image
  /grid/{zoom}/{x}/{y}.grid.json:
    get:
      summary: Grid Tiles UTFGrid
      description: |
        Given zero to many of following parameters, returns a JSON file
        following the UTFGrid spec, representing observations matching
        the search criteria
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "tiles" } ) %>
      tags:
        - UTFGrid
      responses:
        200:
          description: |
            Returns a UTFGrid
          schema:
            $ref: "#/definitions/UTFGridResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /heatmap/{zoom}/{x}/{y}.png:
    get:
      summary: Heatmap Tiles
      description: |
        Given zero to many of following parameters, returns a PNG image
        representing the matching observations within a map tile, following
        the XYZ tiling scheme
      produces:
        - image/png
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "tiles" } ) %>
      tags:
        - Observation Tiles
      responses:
        200:
          description: |
            Returns a PNG map tile image
  /heatmap/{zoom}/{x}/{y}.grid.json:
    get:
      summary: Heatmap Tiles UTFGrid
      description: |
        Given zero to many of following parameters, returns a JSON file
        following the UTFGrid spec, representing observations matching
        the search criteria
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "tiles" } ) %>
      tags:
        - UTFGrid
      responses:
        200:
          description: |
            Returns a UTFGrid
          schema:
            $ref: "#/definitions/UTFGridResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /points/{zoom}/{x}/{y}.png:
    get:
      summary: Points Tiles
      description: |
        Given zero to many of following parameters, returns a PNG image
        representing the matching observations within a map tile, following
        the XYZ tiling scheme
      produces:
        - image/png
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "tiles" } ) %>
      tags:
        - Observation Tiles
      responses:
        200:
          description: |
            Returns a PNG map tile image
  /points/{zoom}/{x}/{y}.grid.json:
    get:
      summary: Points Tiles UTFGrid
      description: |
        Given zero to many of following parameters, returns a JSON file
        following the UTFGrid spec, representing observations matching
        the search criteria
      parameters:
        <%- include( "_observation_search_params_v1.yml.ejs", { type: "tiles" } ) %>
      tags:
        - UTFGrid
      responses:
        200:
          description: |
            Returns a UTFGrid
          schema:
            $ref: "#/definitions/UTFGridResponse"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /places/{place_id}/{zoom}/{x}/{y}.png:
    get:
      summary: Place Tiles
      description: |
        Returns a PNG map tile representing the boundary of this place,
        following the XYZ tiling scheme
      produces:
        - image/png
      parameters:
        - $ref: "#/parameters/path_place_id"
        - $ref: "#/parameters/zoom"
        - $ref: "#/parameters/x"
        - $ref: "#/parameters/y"
        - $ref: "#/parameters/ttl"
      tags:
        - Polygon Tiles
      responses:
        200:
          description: |
            Returns a PNG map tile image
  /taxon_places/{taxon_id}/{zoom}/{x}/{y}.png:
    get:
      summary: Taxon Place Tiles
      description: |
        Returns a PNG map tile representing the boundaries of places this taxon
        is known to occur, following the XYZ tiling scheme
      produces:
        - image/png
      parameters:
        - $ref: "#/parameters/path_taxon_id"
        - $ref: "#/parameters/zoom"
        - $ref: "#/parameters/x"
        - $ref: "#/parameters/y"
        - $ref: "#/parameters/ttl"
      tags:
        - Polygon Tiles
      responses:
        200:
          description: |
            Returns a PNG map tile image
  /taxon_ranges/{taxon_id}/{zoom}/{x}/{y}.png:
    get:
      summary: Taxon Range Tiles
      description: |
        Returns a PNG map tile representing the range of this taxon, following
        the XYZ tiling scheme
      produces:
        - image/png
      parameters:
        - $ref: "#/parameters/path_taxon_id"
        - $ref: "#/parameters/zoom"
        - $ref: "#/parameters/x"
        - $ref: "#/parameters/y"
        - $ref: "#/parameters/tile_color"
        - $ref: "#/parameters/ttl"
      tags:
        - Polygon Tiles
      responses:
        200:
          description: |
            Returns a PNG map tile image
parameters:
  # Obs Search Boolean Params
  acc:
    name: acc
    type: boolean
    in: query
    description: Whether or not positional accuracy / coordinate uncertainty has been specified
  captive:
    name: captive
    type: boolean
    in: query
    description: Captive or cultivated observations
  endemic:
    name: endemic
    type: boolean
    in: query
    description: Observations whose taxa are endemic to their location
  geo:
    name: geo
    type: boolean
    in: query
    description: Observations that are georeferenced
  id_please:
    name: id_please
    type: boolean
    in: query
    description: Observations with the deprecated `ID, Please!` flag. Note that this will return observations, but that this attribute is no longer used.
  ident_user_id:
    name: ident_user_id
    type: integer
    in: query
    description: Observations identified by a particular user
  identified:
    name: identified
    type: boolean
    in: query
    description: Observations that have community identifications
  introduced:
    name: introduced
    type: boolean
    in: query
    description: |
      Observations whose taxa are introduced in their location
  mappable:
    name: mappable
    type: boolean
    in: query
    description: Observations that show on map tiles
  native:
    name: native
    type: boolean
    in: query
    description: Observations whose taxa are native to their location
  out_of_range:
    name: out_of_range
    type: boolean
    in: query
    description: Observations whose taxa are outside their known ranges
  pcid:
    name: pcid
    type: boolean
    in: query
    description: |
      Observations identified by the curator of a project. If
      the `project_id` parameter is also specified, this will only consider
      observations identified by curators of the specified project(s)
  photos:
    name: photos
    type: boolean
    in: query
    description: Observations with photos
  popular:
    name: popular
    type: boolean
    in: query
    description: |
      Observations that have been favorited by at least one user
  sounds:
    name: sounds
    type: boolean
    in: query
    description: Observations with sounds
  taxon_is_active:
    name: taxon_is_active
    type: boolean
    in: query
    description: |
      Observations of active taxon concepts
  threatened:
    name: threatened
    type: boolean
    in: query
    description: |
      Observations whose taxa are threatened in their location
  verifiable:
    name: verifiable
    type: boolean
    in: query
    description: |
      Observations with a `quality_grade` of either `needs_id` or
      `research`. Equivalent to `quality_grade=needs_id,research`
  licensed:
    name: licensed
    type: boolean
    in: query
    description: License attribute of an observation must not be null
  photo_licensed:
    name: photo_licensed
    type: boolean
    in: query
    description: License attribute of at least one photo of an observation must not be null
  expected_nearby:
    name: expected_nearby
    type: boolean
    in: query
    description: Observation taxon is expected nearby
  # Obs Search Multi-Value Params
  hour:
    name: hour
    type: array
    items:
      type: string
    in: query
    minimum: 0
    maximum: 23
    description: Must be observed within this hour of the day
  day:
    name: day
    type: array
    items:
      type: string
    in: query
    minimum: 1
    maximum: 31
    description: Must be observed within this day of the month
  created_day:
    name: created_day
    type: array
    items:
      type: string
    in: query
    minimum: 1
    maximum: 31
    description: Must be created within this day of the month
  id:
    name: id
    type: array
    items:
      type: string
    in: query
    minimum: 1
    description: Must have this ID
  not_id:
    name: not_id
    type: array
    items:
      type: string
    in: query
    minimum: 1
    description: Must not have this ID
  license:
    name: license
    type: array
    items:
      type: string
    in: query
    description: Observation must have this license
    enum:
      - cc-by
      - cc-by-nc
      - cc-by-nd
      - cc-by-sa
      - cc-by-nc-nd
      - cc-by-nc-sa
      - cc0
  month:
    name: month
    type: array
    items:
      type: string
    in: query
    minimum: 1
    maximum: 12
    description: Must be observed within this month
  created_month:
    name: created_month
    type: array
    items:
      type: string
    in: query
    minimum: 1
    maximum: 12
    description: Must be created within this month
  term_id:
    name: term_id
    type: array
    items:
      type: integer
    in: query
    description: Must have an annotation using this controlled term ID
  term_value_id:
    name: term_value_id
    type: array
    items:
      type: integer
    in: query
    description: |
      Must have an annotation using this controlled value ID. Must be combined
      with the `term_id` parameter
  without_term_id:
    name: without_term_id
    type: integer
    in: query
    description: |
      Exclude observations with annotations using this controlled value ID.
  without_term_value_id:
    name: without_term_value_id
    type: array
    items:
      type: integer
    in: query
    description: |
      Exclude observations with annotations using this controlled value ID.
      Must be combined with the `term_id` parameter
  term_id_or_unknown:
    name: term_id_or_unknown
    type: array
    items:
      type: integer
    in: query
    description: |
      Must be combined with the `term_value_id` or the `without_term_value_id` parameter.
      Must have an annotation using this controlled term ID and associated term value IDs
      or be missing this annotation.
  annotation_user_id:
    name: annotation_user_id
    type: array
    items:
      type: string
    in: query
    description: |
      Must have an annotation created by this user
  ofv_datatype:
    name: ofv_datatype
    type: array
    items:
      type: string
    in: query
    minimum: 1
    maximum: 31
    description: Must have an observation field value with this datatype
  photo_license:
    name: photo_license
    type: array
    items:
      type: string
    in: query
    description: Must have at least one photo with this license
    enum:
      - cc-by
      - cc-by-nc
      - cc-by-nd
      - cc-by-sa
      - cc-by-nc-nd
      - cc-by-nc-sa
      - cc0
  place_id:
    name: place_id
    type: array
    items:
      type: integer
    in: query
    description: Must be observed within the place with this ID
  project_id:
    name: project_id
    type: array
    items:
      type: string
    in: query
    description: Must be added to the project this ID or slug
  rank:
    name: rank
    type: array
    items:
      type: string
    in: query
    description: Taxon must have this rank
    enum:
      <%- include( "_ranks.yml.ejs" ) %>
  site_id:
    name: site_id
    type: array
    items:
      type: string
    in: query
    description: |
      Must be affiliated with the iNaturalist network website with this ID
  sound_license:
    name: sound_license
    type: array
    items:
      type: string
    in: query
    description: Must have at least one sound with this license
    enum:
      - cc-by
      - cc-by-nc
      - cc-by-nd
      - cc-by-sa
      - cc-by-nc-nd
      - cc-by-nc-sa
      - cc0
  taxon_id:
    name: taxon_id
    type: array
    items:
      type: string
    in: query
    minimum: 1
    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
    items:
      type: string
    in: query
    description: |
      Taxon must have a scientific or common name matching this string
  user_id:
    name: user_id
    type: array
    items:
      type: string
    in: query
    minimum: 1
    description: User must have this ID or login
  user_login:
    name: user_login
    type: array
    items:
      type: string
    in: query
    description: User must have this login
  year:
    name: year
    type: array
    items:
      type: string
    in: query
    minimum: 1
    description: Must be observed within this year
  created_year:
    name: created_year
    type: array
    items:
      type: string
    in: query
    minimum: 1
    description: Must be created within this year
  # Remaining Obs Search Params
  acc_above:
    name: acc_above
    type: string
    in: query
    description: Must have a positional accuracy above this value (meters)
  acc_below:
    name: acc_below
    type: string
    in: query
    description: Must have a positional accuracy below this value (meters)
  acc_below_or_unknown:
    name: acc_below_or_unknown
    type: string
    in: query
    description: Positional accuracy must be below this value (in meters) or be unknown
  apply_project_rules_for:
    name: apply_project_rules_for
    type: string
    in: query
    description: Must match the rules of the project with this ID or slug
  created_d1:
    name: created_d1
    type: string
    format: date-time
    in: query
    description: Must be created at or after this time
  created_d2:
    name: created_d2
    type: string
    format: date-time
    in: query
    description: Must be created at or before this time
  created_on:
    name: created_on
    type: string
    format: date
    in: query
    description: Must be created on this date
  cs:
    name: cs
    type: string
    in: query
    description: |
      Taxon must have this conservation status code. If
      the `place_id` parameter is also specified, this will only consider
      statuses specific to that place
  csa:
    name: csa
    type: string
    in: query
    description: |
      Taxon must have a conservation status from this authority. If
      the `place_id` parameter is also specified, this will only consider
      statuses specific to that place
  csi:
    name: csi
    type: array
    items:
      type: string
    in: query
    description: |
      Taxon must have this IUCN conservation status. If
      the `place_id` parameter is also specified, this will only consider
      statuses specific to that place
    enum:
      - LC
      - NT
      - VU
      - EN
      - CR
      - EW
      - EX
  d1:
    name: d1
    type: string
    format: date
    in: query
    description: Must be observed on or after this date
  d2:
    name: d2
    type: string
    format: date
    in: query
    description: Must be observed on or before this date
  geoprivacy:
    name: geoprivacy
    type: array
    items:
      type: string
    in: query
    description: Must have this geoprivacy setting
    enum:
      - obscured
      - obscured_private
      - open
      - private
  taxon_geoprivacy:
    name: taxon_geoprivacy
    type: array
    items:
      type: string
    in: query
    description: |
      Filter observations by the most conservative geoprivacy applied by a
      conservation status associated with one of the taxa proposed in the
      current identifications.
    enum:
      - obscured
      - obscured_private
      - open
      - private
  obscuration:
    name: obscuration
    type: array
    items:
      type: string
    in: query
    description: |
      Must have `geoprivacy` or `taxon_geoprivacy` fields matching these values
    enum:
      - obscured
      - private
      - none
  hrank:
    name: hrank
    type: string
    in: query
    description: Taxon must have this rank or lower
    enum:
      <%- include( "_ranks.yml.ejs" ) %>
  iconic_taxa:
    name: iconic_taxa
    type: array
    items:
      type: string
    in: query
    description: Taxon must by within this iconic taxon
    enum:
      - Actinopterygii
      - Animalia
      - Amphibia
      - Arachnida
      - Aves
      - Chromista
      - Fungi
      - Insecta
      - Mammalia
      - Mollusca
      - Reptilia
      - Plantae
      - Protozoa
      - unknown
  id_above:
    name: id_above
    type: string
    in: query
    description: Must have an ID above this value
  id_below:
    name: id_below
    type: string
    in: query
    description: Must have an ID below this value
  identifications:
    name: identifications
    type: string
    in: query
    description: Identifications must meet these criteria
    enum:
      - most_agree
      - most_disagree
      - some_agree
  lat:
    name: lat
    type: number
    format: double
    in: query
    description: |
      Must be within a {`radius`} kilometer circle around this lat/lng
      (*lat, *lng, radius)
  list_id:
    name: list_id
    type: integer
    in: query
    description: Taxon must be in the list with this ID
  lng:
    name: lng
    type: number
    format: double
    in: query
    description: |
      Must be within a {`radius`} kilometer circle around this lat/lng
      (*lat, *lng, radius)
  lrank:
    name: lrank
    type: string
    in: query
    description: Taxon must have this rank or higher
    enum:
      <%- include( "_ranks.yml.ejs" ) %>
  nelat:
    name: nelat
    type: number
    format: double
    in: query
    description: |
      Must be within this bounding box (*nelat, *nelng, *swlat, *swlng)
  nelng:
    name: nelng
    type: number
    format: double
    in: query
    description: |
      Must be within this bounding box (*nelat, *nelng, *swlat, *swlng)
  swlat:
    name: swlat
    type: number
    format: double
    in: query
    description: |
      Must be within this bounding box (*nelat, *nelng, *swlat, *swlng)
  swlng:
    name: swlng
    type: number
    format: double
    in: query
    description: |
      Must be within this bounding box (*nelat, *nelng, *swlat, *swlng)
  not_in_project:
    name: not_in_project
    type: string
    in: query
    description: Must not be in the project with this ID or slug
  not_matching_project_rules_for:
    name: not_matching_project_rules_for
    type: string
    in: query
    description: Must not match the rules of the project with this ID or slug
  observation_accuracy_experiment_id:
    name: observation_accuracy_experiment_id
    type: array
    items:
      type: integer
    in: query
    description: Must included in this observation accuracy experiment
  unobserved_by_user_id:
    name: unobserved_by_user_id
    type: integer
    in: query
    description: Must not be of a taxon previously observed by this user
  observed_on:
    name: observed_on
    type: string
    format: date
    in: query
    description: Must be observed on this date
  order:
    name: order
    type: string
    in: query
    description: Sort order
    default: desc
    enum:
      - desc
      - asc
  order_by:
    name: order_by
    type: string
    in: query
    description: Sort field
    default: created_at
    enum:
      - created_at
      - geo_score
      - id
      - observed_on
      - random
      - species_guess
      - updated_at
      - votes
  only_id:
    name: only_id
    type: boolean
    in: query
    description: Return only the record IDs
  page:
    name: page
    type: string
    in: query
    description: Pagination `page` number
  per_page:
    name: per_page
    type: string
    in: query
    description: |
      Number of results to return in a `page`. The maximum value is generally
      200 unless otherwise noted
  per_page_species_counts:
    name: per_page
    type: string
    in: query
    description: |
      Number of results to return in a `page`. The maximum value is 500
  q:
    name: q
    type: string
    in: query
    description: Search observation properties. Can be combined with `search_on`
  quality_grade:
    name: quality_grade
    type: string
    in: query
    description: Must have this quality grade
    enum:
      - casual
      - needs_id
      - research
  radius:
    name: radius
    type: string
    in: query
    description: |
      Must be within a {`radius`} kilometer circle around this lat/lng
      (*lat, *lng, radius)
  search_on:
    name: search_on
    type: string
    in: query
    description: |
      Properties to search on, when combined with `q`.
      Searches across all properties by default
    enum:
      - names
      - tags
      - description
      - place
  ttl:
    name: ttl
    type: string
    in: query
    description: |
      Set the `Cache-Control` HTTP header with this value as `max-age`, in
      seconds. This means subsequent identical requests will be cached on
      iNaturalist servers, and commonly within web browsers
  updated_since:
    name: updated_since
    type: string
    in: query
    description: Must be updated since this time
  viewer_id:
    name: viewer_id
    type: string
    in: query
    description: See `reviewed`
  reviewed:
    name: reviewed
    type: boolean
    in: query
    description: |
      Observations have been reviewed by the user with ID equal to
      the value of the `viewer_id` parameter
  annotation_path_id:
    name: id
    in: path
    required: true
    type: string
    description: ID or UUID of the annotation
  path_id:
    name: id
    in: path
    required: true
    type: integer
    description: ID of the record
  path_multi_id:
    name: id
    in: path
    required: true
    type: array
    items:
      type: integer
    description: Must have this ID
  path_multi_id_or_slug:
    name: id
    in: path
    required: true
    type: array
    items:
      type: string
    description: Must have this ID or slug
  autocomplete_q:
    name: q
    type: string
    in: query
    required: true
    description: Search by name (must start with this value) or by ID (exact match).
  autocomplete_q_not_required:
    name: q
    type: string
    in: query
    description: Search by name (must start with this value) or by ID (exact match).
  autocomplete_project_id:
    name: project_id
    type: integer
    in: query
    description: Only show users with memberships to this project
  # Taxa
  rank_level:
    name: rank_level
    type: number
    in: query
    description: |
      Taxon must have this rank level. Some example values are 70 (kingdom),
      60 (phylum), 50 (class), 40 (order), 30 (family), 20 (genus),
      10 (species), 5 (subspecies)
  parent_id:
    name: parent_id
    type: integer
    in: query
    description: Taxon's parent must have this ID
  taxa_order_by:
    name: order_by
    type: string
    in: query
    description: Sort field
    default: observations_count
    enum:
      - id
      - created_at
      - observations_count
  # Nearby Places
  nelat_required:
    name: nelat
    type: number
    format: double
    in: query
    required: true
    description: |
      Must be nearby this bounding box (*nelat, *nelng, *swlat, *swlng)
  nelng_required:
    name: nelng
    type: number
    format: double
    in: query
    required: true
    description: |
      Must be nearby this bounding box (*nelat, *nelng, *swlat, *swlng)
  swlat_required:
    name: swlat
    type: number
    format: double
    in: query
    required: true
    description: |
      Must be nearby this bounding box (*nelat, *nelng, *swlat, *swlng)
  swlng_required:
    name: swlng
    type: number
    format: double
    in: query
    required: true
    description: |
      Must be nearby this bounding box (*nelat, *nelng, *swlat, *swlng)
  # Locale Params
  locale:
    name: locale
    type: string
    in: query
    description: |
      Locale preference for taxon common names
  preferred_place_id:
    name: preferred_place_id
    type: integer
    in: query
    description: |
      Place preference for regional taxon common names
  # Tile Params
  zoom:
    name: zoom
    type: integer
    in: path
    required: true
    minimum: 0
    maximum: 21
    description: Zoom level. Z coordinate in the XYZ tiling scheme
  x:
    name: x
    type: integer
    in: path
    required: true
    minimum: 0
    description: X coordinate in the XYZ tiling scheme. Must be less than 2^zoom
  y:
    name: y
    type: integer
    in: path
    required: true
    minimum: 0
    description: Y coordinate in the XYZ tiling scheme. Must be less than 2^zoom
  path_place_id:
    name: place_id
    type: integer
    in: path
    required: true
    description: Place ID
  path_taxon_id:
    name: taxon_id
    type: integer
    in: path
    required: true
    description: Taxon ID
  tile_color:
    name: color
    type: string
    in: query
    description: |
      Primary color to use in tile creation. Accepts common colors by string
      (e.g. `color=blue`), and accepts escaped color HEX codes
      (e.g. `color=%2386a91c`)
  path_metric:
    name: metric
    in: path
    required: true
    type: string
    description: Data quality category
    enum:
      - date
      - location
      - wild
  date_field:
    name: date_field
    in: query
    required: false
    type: string
    description: |
      Histogram basis: when the observation was created or observed
    default: observed
    enum:
      - created
      - observed
  interval:
    name: interval
    in: query
    required: false
    type: string
    description: |
      Time interval for histogram, with groups starting on or contained within
      the group value. The year, month, week, day, and hour options will set
      default values for `d1` or `created_d1` depending on the value of
      `date_field`, to limit the number of groups returned. You can override
      those values if you want data from a longer or shorter time span. The
      `hour` interval only works with `date_field=created`, and this you
      should filter dates with `created_d[1,2]`
    default: month_of_year
    enum:
      - year
      - month
      - week
      - day
      - hour
      - month_of_year
      - week_of_year
  created_after:
    name: created_after
    type: string
    format: date-time
    in: query
    description: Must be created at or after this time
  viewed:
    name: viewed
    type: boolean
    in: query
    description: Notification has been viewed by the user before
  observations_by:
    name: observations_by
    type: string
    in: query
    description: |
      Only show updates on observations owned by the currently authenticated
      user or on observations the authenticated user is following but does not
      own.
    enum:
      - owner
      - following
  since:
    name: since
    type: string
    format: date-time
    in: query
    required: true
    description: Deleted at or after this time
  # identifications
  ids_current_taxon:
    name: current_taxon
    type: boolean
    in: query
    description: ID's taxon is the same it's observation's taxon
  ids_own_observation:
    name: own_observation
    type: boolean
    in: query
    description: ID was added by the observer
  ids_is_change:
    name: is_change
    type: boolean
    in: query
    description: ID was created as a results of a taxon change
  ids_taxon_active:
    name: taxon_active
    type: boolean
    in: query
    description: ID's taxon is currently an active taxon
  ids_observation_taxon_active:
    name: observation_taxon_active
    type: boolean
    in: query
    description: Observation's taxon is currently an active taxon
  ids_id:
    name: id
    type: array
    items:
      type: integer
    in: query
    description: Identification ID
  ids_rank:
    name: rank
    type: array
    items:
      type: string
    in: query
    description: ID's taxon must have this rank
    enum:
      <%- include( "_ranks.yml.ejs" ) %>
  ids_observation_rank:
    name: observation_rank
    type: array
    items:
      type: string
    in: query
    description: Observation's taxon must have this rank
    enum:
      <%- include( "_ranks.yml.ejs" ) %>
  ids_user_id:
    name: user_id
    type: array
    items:
      type: integer
    in: query
    minimum: 1
    description: Identifier must have this user ID
  ids_user_login:
    name: user_login
    type: array
    items:
      type: string
    in: query
    description: Identifier must have this login
  ids_current:
    name: current
    type: boolean
    in: query
    description: Most recent ID on a observation by a user
    enum:
      - true
      - false
      - any
    default: true
  ids_category:
    name: category
    type: array
    items:
      type: string
    in: query
    enum:
      - improving
      - supporting
      - leading
      - maverick
    description: Type of identification
  ids_place_id:
    name: place_id
    type: array
    items:
      type: string
    in: query
    description: Observation must occur in this place
  ids_quality_grade:
    name: quality_grade
    type: array
    items:
      type: string
    in: query
    description: Observation must have this quality grade
    enum:
      - casual
      - needs_id
      - research
  ids_taxon_id:
    name: taxon_id
    type: array
    items:
      type: string
    in: query
    minimum: 1
    description: ID taxa must match the given taxa or their descendants
  ids_observation_taxon_id:
    name: observation_taxon_id
    type: array
    items:
      type: string
    in: query
    minimum: 1
    description: Observation taxa must match the given taxa or their descendants
  ids_iconic_taxon_id:
    name: iconic_taxon_id
    type: array
    items:
      type: string
    in: query
    minimum: 1
    description: ID iconic taxon ID
  ids_observation_iconic_taxon_id:
    name: observation_iconic_taxon_id
    type: array
    items:
      type: string
    in: query
    minimum: 1
    description: Observation iconic taxon ID
  ids_lrank:
    name: lrank
    type: string
    in: query
    description: ID taxon must have this rank or higher
    enum:
      <%- include( "_ranks.yml.ejs" ) %>
  ids_hrank:
    name: hrank
    type: string
    in: query
    description: ID taxon must have this rank or lower
    enum:
      <%- include( "_ranks.yml.ejs" ) %>
  ids_observation_lrank:
    name: observation_lrank
    type: string
    in: query
    description: Observation taxon must have this rank or higher
    enum:
      <%- include( "_ranks.yml.ejs" ) %>
  ids_observation_hrank:
    name: observation_hrank
    type: string
    in: query
    description: Observation taxon must have this rank or lower
    enum:
      <%- include( "_ranks.yml.ejs" ) %>
  ids_without_taxon_id:
    name: without_taxon_id
    type: array
    items:
      type: string
    in: query
    minimum: 1
    description: Exclude IDs of these taxa and their descendants
  ids_without_observation_taxon_id:
    name: without_observation_taxon_id
    type: array
    items:
      type: string
    in: query
    minimum: 1
    description: Exclude IDs of observations of these taxa and their descendants
  ids_d1:
    name: d1
    type: string
    format: date
    in: query
    description: ID created on or after this time
  ids_d2:
    name: d2
    type: string
    format: date
    in: query
    description: ID created on or before this time
  ids_observation_created_d1:
    name: observation_created_d1
    type: string
    format: date
    in: query
    description: Observation created on or after this date
  ids_observation_created_d2:
    name: observation_created_d2
    type: string
    format: date
    in: query
    description: Observation created on or before this date
  ids_observed_d1:
    name: observed_d1
    type: string
    format: date
    in: query
    description: Observation observed on or after this date
  ids_observed_d2:
    name: observed_d2
    type: string
    format: date
    in: query
    description: Observation observed on or before this date
  ids_order_by:
    name: order_by
    type: string
    in: query
    description: Sort field
    default: created_at
    enum:
      - created_at
      - id
  taxa_taxon_id:
    name: taxon_id
    type: array
    items:
      type: string
    in: query
    minimum: 1
    description: Only show taxa with this ID, or its descendants
  all_names:
    name: all_names
    type: boolean
    in: query
    description: Include all taxon names in the response
  include_ancestors:
    name: include_ancestors
    type: boolean
    in: query
    description: Include taxon ancestors in the response
    default: false
  # projects
  projects_radius:
    name: radius
    type: string
    in: query
    description: |
      Must be within a {`radius`} kilometer circle around this lat/lng
      (*lat, *lng, radius). Defaults to 500km
  associated_place_id:
    name: place_id
    type: array
    items:
      type: string
    in: query
    description: Must be associated with this place
  featured:
    name: featured
    type: string
    in: query
    enum:
      - true
    description: Must be marked featured for the relevant site
  noteworthy:
    name: noteworthy
    type: string
    in: query
    enum:
      - true
    description: Must be marked noteworthy for the relevant site
  projects_site_id:
    name: site_id
    type: integer
    in: query
    description: |
      Site ID that applies to `featured` and `noteworthy`. Defaults to the site
      of the authenticated user, or to the main iNaturalist site
      https://www.inaturalist.org
  type:
    name: type
    type: array
    items:
      type: string
    enum:
      - collection
      - umbrella
    in: query
    description: Projects must be of this type
  member_id:
    name: member_id
    type: integer
    in: query
    description: Project must have member with this user ID
  has_params:
    name: has_params
    type: boolean
    in: query
    description: Must have search parameter requirements
  has_posts:
    name: has_posts
    type: boolean
    in: query
    description: Must have posts
  projects_order_by:
    name: order_by
    type: string
    in: query
    description: Sort field
    enum:
      - recent_posts
      - created
      - updated
      - distance
      - featured
    description: |
      Sort order. `distance` only applies if `lat` and `lng` are specified.
      `featured` only applies if `featured` or `noteworthy` are true
  project_type:
    name: project_type
    type: string
    in: query
    enum:
      - traditional
      - collection
      - umbrella
    description: |
      Specify the type of project to return
  skip_counts:
    name: skip_counts
    type: boolean
    default: false
    in: query
    description: |
      If counts are not needed, consider setting this to true to save on
      processing time, resulting in faster responses
  # posts
  posts_login:
    name: login
    type: string
    in: query
    description: Return posts by this user
  posts_project_id:
    name: project_id
    type: integer
    in: query
    description: Return posts from this project
  rule_details:
    name: rule_details
    type: string
    in: query
    enum:
      - true
    description: |
      Return more information about project rules, for example return a full
      taxon object instead of simply an ID
  # search
  sources:
    name: sources
    type: array
    items:
      type: string
    enum:
      - places
      - projects
      - taxa
      - users
    in: query
    description: Must be of this type
  search_q:
    name: q
    type: string
    in: query
    description: Search object properties
  include_taxon_ancestors:
    name: include_taxon_ancestors
    type: boolean
    in: query
    description: Include taxon ancestors in the response
    default: false


securityDefinitions:
  api_token:
    type: apiKey
    name: Authorization
    in: header
definitions:
  AutocompleteTaxon:
    allOf:
      - $ref: "#/definitions/CoreTaxon"
      - type: object
        properties:
          default_photo:
            $ref: "#/definitions/TaxonPhoto"
          matched_term:
            type: string
          observations_count:
            type: integer
  BaseResponse:
    type: object
    properties:
      total_results:
        type: integer
      page:
        type: integer
      per_page:
        type: integer
  Color:
    type: object
    properties:
      id:
        type: integer
      value:
        type: string
  Comment:
    type: object
    properties:
      id:
        type: integer
      created_at:
        type: string
        format: date-time
      created_at_details:
        $ref: "#/definitions/DateDetails"
      user:
        $ref: "#/definitions/User"
  PostAnnotation:
    type: object
    properties:
      annotation:
        type: object
        properties:
          resource_type:
            type: string
            enum:
              - Observation
          resource_id:
            type: integer
          controlled_attribute_id:
            type: integer
          controlled_value_id:
            type: integer
  PostComment:
    type: object
    properties:
      comment:
        type: object
        properties:
          parent_type:
            type: string
            enum:
              - Observation
              - ListedTaxon
              - AssessmentSection
              - ObservationField
              - Post
              - TaxonChange
          parent_id:
            type: integer
          body:
            type: string
  PostFlag:
    type: object
    properties:
      flag:
        type: object
        properties:
          flaggable_type:
            type: string
            enum:
              - Comment
              - Identification
              - Message
              - Observation
              - Post
              - Taxon
          flaggable_id:
            type: integer
          flag:
            enum:
              - spam
              - inappropriate
              - other
      flag_explanation:
        type: string
  PostIdentification:
    type: object
    properties:
      identification:
        type: object
        properties:
          observation_id:
            type: integer
          taxon_id:
            type: integer
          current:
            type: boolean
          body:
            type: string
  PostMessage:
    type: object
    properties:
      message:
        type: object
        properties:
          to_user_id:
            type: integer
            description: User ID of the recipient
          thread_id:
            type: integer
            description: |
              Identifier for the thread. Should be blank for new threads,
              but when replying to an existing message, it should be set to
              the thread_id of the message being replied to.
          subject:
            type: string
            description: Subject of the message
          body:
            type: string
            description: Body of the message
  PostPost:
    type: object
    properties:
      commit:
        type: string
        example: Publish
      post:
        type: object
        properties:
          title:
            type: string
          body:
            type: string
          preferred_formatting:
            type: string
            example: simple
          user_id:
            type: number
          parent_id:
            type: number
          parent_type:
            type: string
            example: Project
  PostObservation:
    type: object
    properties:
      observation:
        type: object
        properties:
          species_guess:
            type: string
          taxon_id:
            type: integer
          description:
            type: string
  PostObservationFieldValue:
    type: object
    properties:
      observation_field_value:
        type: object
        properties:
          observation_id:
            type: integer
          observation_field_id:
            type: integer
          value:
            type: string
  PostObservationPhoto:
    type: object
    properties:
      observation_photo:
        type: object
        properties:
          observation_id:
            type: integer
  PostObservationVote:
    type: object
    properties:
      vote:
        type: string
        enum:
          - up
          - down
      scope:
        enum:
          - needs_id
  PostProjectAdd:
    type: object
    properties:
      observation_id:
        type: integer
  PostProjectObservation:
    type: object
    properties:
      project_id:
        type: integer
      observation_id:
        type: integer
  UpdateProjectObservation:
    type: object
    properties:
      project_observation:
        type: object
        properties:
          project_id:
            type: integer
          observation_id:
            type: integer
          prefers_curator_coordinate_access:
            type: boolean
  PostQuality:
    type: object
    properties:
      agree:
        type: boolean
  PostVote:
    type: object
    properties:
      vote:
        type: string
        enum:
          - up
          - down
  PostUser:
    type: object
    properties:
      user:
        type: object
        properties:
          login:
            type: string
          email:
            type: string
          name:
            type: string
            description: Display name for this user
          locale:
            type: string
            description: |
              Locale code for language/region localization. See
              https://github.com/inaturalist/inaturalist/tree/master/config/locales
              for available locales. Valid strings can be derived from file
              names, e.g. `es-MX` from `es-MX.yml`.
          time_zone:
            type: string
            description: |
              Default time zone for the user's observations. See
              http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html
              for a list of values.
          place_id:
            type: integer
            description: |
              ID of the place for this user, customizes some common names and
              default search parameters
          description:
            type: string
            description: User profile description
          icon:
            type: object
            description: |
              User's profile pic. Requires POST/PUT as a multipart request.
      icon_delete:
        type: boolean
        default: false
        description: Set to true to remove the current user icon.
  PostUserUpdateSession:
    type: object
    properties:
      preferred_taxon_page_ancestors_shown:
        type: boolean
      preferred_taxon_page_place_id:
        type: integer
      preferred_taxon_page_tab:
        type: string
      prefers_skip_coarer_id_modal:
        type: boolean
      prefers_hide_obs_show_annotations:
        type: boolean
      prefers_hide_obs_show_projects:
        type: boolean
      prefers_hide_obs_show_tags:
        type: boolean
      prefers_hide_obs_show_observation_fields:
        type: boolean
      prefers_hide_obs_show_identifiers:
        type: boolean
      prefers_hide_obs_show_copyright:
        type: boolean
      prefers_hide_obs_show_quality_metrics:
        type: boolean
  PutFlag:
    type: object
    properties:
      flag:
        type: object
        properties:
          resolved:
            type: boolean
  ConservationStatus:
    type: object
    properties:
      place_id:
        type: integer
      place:
        $ref: "#/definitions/CorePlace"
      status:
        type: string
  CorePlace:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      display_name:
        type: string
  CoreTaxon:
    type: object
    properties:
      id:
        type: integer
      iconic_taxon_id:
        type: integer
      iconic_taxon_name:
        type: string
      is_active:
        type: boolean
      name:
        type: string
      preferred_common_name:
        type: string
      rank:
        type: string
      rank_level:
        type: number
  DateDetails:
    type: object
    properties:
      date:
        type: string
        format: date
      day:
        type: integer
      hour:
        type: integer
      month:
        type: integer
      week:
        type: integer
      year:
        type: integer
  EstablishmentMeans:
    type: object
    properties:
      establishment_means:
        type: string
      place:
        $ref: "#/definitions/CorePlace"
  Fave:
    type: object
    properties:
      id:
        type: integer
      votable_id:
        type: integer
      created_at:
        type: string
        format: date-time
      user:
        $ref: "#/definitions/User"
  FieldValue:
    type: object
    properties:
      name:
        type: string
      value:
        type: string
  Identification:
    type: object
    properties:
      id:
        type: integer
      observation_id:
        type: integer
      body:
        type: string
      created_at:
        type: string
        format: date-time
      updated_at:
        type: string
        format: date-time
      current:
        type: boolean
      taxon:
        $ref: "#/definitions/ObservationTaxon"
  Message:
    type: object
    properties:
      id:
        type: integer
      subject:
        type: string
      body:
        type: string
      user_id:
        type: integer
        description: |
          ID of the user to whom this message belongs. Messages work like email,
          so the sender gets a copy and the recipient gets a copy of each
          message. This is always the authenticated user, so there's no real
          need for a full user object.
      to_user:
        $ref: "#/definitions/User"
      from_user:
        $ref: "#/definitions/User"
      thread_id:
        type: integer
        description: |
          Identifier for the message thread, generally the ID of the sender's
          copy of the first message
      thread_messages_count:
        type: integer
        description: |
          Number of messages in this thread. Only included when threads=true
      thread_flags:
        type: array
        description: |
          Array of flags on messages in this thread. Only included when
          threads=true
        items:
          type: object
  NonOwnerIdentification:
    type: object
    properties:
      id:
        type: integer
      body:
        type: string
      created_at:
        type: string
        format: date-time
      created_at_details:
        $ref: "#/definitions/DateDetails"
      user:
        $ref: "#/definitions/User"
  Observation:
    type: object
    properties:
      id:
        type: integer
      cached_votes_total:
        type: integer
      captive:
        type: boolean
      comments:
        type: array
        items:
          $ref: "#/definitions/Comment"
      comments_count:
        type: integer
      created_at:
        type: string
        format: date-time
      created_at_details:
        $ref: "#/definitions/DateDetails"
      created_time_zone:
        type: string
      description:
        type: string
      faves_count:
        type: integer
      geojson:
        $ref: "#/definitions/PointGeoJson"
      geoprivacy:
        type: string
      taxon_geoprivacy:
        type: string
      id_please:
        type: boolean
      identifications_count:
        type: integer
      identifications_most_agree:
        type: boolean
      identifications_most_disagree:
        type: boolean
      identifications_some_agree:
        type: boolean
      license_code:
        type: string
      location:
        type: string
        description: in the format "lat,lng"
      mappable:
        type: boolean
      non_owner_ids:
        type: array
        items:
          $ref: "#/definitions/NonOwnerIdentification"
      num_identification_agreements:
        type: integer
      num_identification_disagreements:
        type: integer
      obscured:
        type: boolean
      observed_on:
        type: string
        format: date-time
      observed_on_details:
        $ref: "#/definitions/DateDetails"
      observed_on_string:
        type: string
      observed_time_zone:
        type: string
      ofvs:
        type: array
        items:
          $ref: "#/definitions/FieldValue"
      out_of_range:
        type: boolean
      photos:
        type: array
        items:
          $ref: "#/definitions/Photo"
      place_guess:
        type: string
      place_ids:
        type: array
        items:
          type: integer
      project_ids:
        type: array
        items:
          type: integer
      project_ids_with_curator_id:
        type: array
        items:
          type: integer
      project_ids_without_curator_id:
        type: array
        items:
          type: integer
      quality_grade:
        type: string
      reviewed_by:
        type: array
        items:
          type: integer
      site_id:
        type: integer
      sounds:
        type: array
        items:
          $ref: "#/definitions/Sound"
      species_guess:
        type: string
      tags:
        type: array
        items:
          type: string
      taxon:
        $ref: "#/definitions/ObservationTaxon"
      time_observed_at:
        type: string
        format: date-time
      time_zone_offset:
        type: string
      updated_at:
        type: string
        format: date-time
      uri:
        type: string
      user:
        $ref: "#/definitions/User"
      verifiable:
        type: boolean
  ObservationTaxon:
    allOf:
      - $ref: "#/definitions/CoreTaxon"
      - type: object
        properties:
          ancestor_ids:
            type: array
            items:
              type: integer
          ancestry:
            type: string
          conservation_status:
            $ref: "#/definitions/RawConservationStatus"
          endemic:
            type: boolean
          establishment_means:
            $ref: "#/definitions/EstablishmentMeans"
          introduced:
            type: boolean
          native:
           type: boolean
          threatened:
            type: boolean
  Photo:
    type: object
    properties:
      id:
        type: integer
      attribution:
        type: string
      license_code:
        type: string
      url:
        type: string
  PointGeoJson:
    type: object
    properties:
      type:
        type: string
      coordinates:
        type: array
        description: an array of [long, lat]
        items:
          type: number
          format: double
  PolygonGeoJson:
    type: object
    properties:
      type:
        type: string
      coordinates:
        type: array
        items:
          type: array
          items:
            type: array
            description: an array of [long, lat]
            items:
              type: number
              format: double
  Project:
    type: object
    properties:
      id:
        type: integer
      title:
        type: string
      description:
        type: string
      slug:
        type: string
  ProjectMember:
    type: object
    properties:
      id:
        type: integer
      project_id:
        type: integer
      created_at:
        type: string
        format: date-time
      updated_at:
        type: string
        format: date-time
      role:
        type: string
        enum:
          - curator
          - manager
      observations_count:
        type: integer
      taxa_count:
        type: integer
      user:
        $ref: "#/definitions/User"
  RawConservationStatus:
    type: object
    properties:
      source_id:
        type: integer
        description: |
          Identifier for the iNat source record associated with this status,
          retrievable via https://www.inaturalist.org/sources/:id.json
          (this endpoint is not a part of our public API and is thus subject to
          change or removal)
      authority:
        type: string
        description: |
          Organization that declared this status
      status:
        type: string
        description: |
          Body of the status, often coded, particularly when the status comes
          from the IUCN or NatureServe. Consult the authority and/or the
          status URL for details about the meanings of codes.
      status_name:
        type: string
        description: |
          Human-readable name of the status if it was coded.
      iucn:
        type: integer
        description: |
          Coded value representing the equivalent IUCN status. Mappings:
          NOT_EVALUATED = 0, DATA_DEFICIENT = 5, LEAST_CONCERN = 10,
          NEAR_THREATENED = 20, VULNERABLE = 30, ENDANGERED = 40,
          CRITICALLY_ENDANGERED = 50, EXTINCT_IN_THE_WILD = 60, EXTINCT = 70
      geoprivacy:
        type: string
        description: |
          Default geoprivacy for observations of this taxon in the status's place.
  TaxonConservationStatus:
    allOf:
      - $ref: "#/definitions/RawConservationStatus"
      - type: object
        properties:
          place:
            $ref: "#/definitions/CorePlace"
  ShowObservation:
    allOf:
      - $ref: "#/definitions/Observation"
      - type: object
        properties:
          identifications:
            type: array
            items:
              $ref: "#/definitions/Identification"
          faves:
            type: array
            items:
              $ref: "#/definitions/Fave"
  ShowPlace:
    allOf:
      - $ref: "#/definitions/CorePlace"
      - type: object
        properties:
          admin_level:
            type: integer
          ancestor_place_ids:
            type: array
            items:
              type: integer
          bbox_area:
            type: number
            format: double
          geometry_geojson:
            $ref: "#/definitions/PolygonGeoJson"
          location:
            type: string
            description: in the format "lat,lng"
          name:
            type: string
          place_type:
            type: integer
  ShowTaxon:
    allOf:
      - $ref: "#/definitions/CoreTaxon"
      - type: object
        properties:
          ancestor_ids:
            type: array
            items:
              type: integer
          colors:
            type: array
            items:
              $ref: "#/definitions/Color"
          conservation_status:
            $ref: "#/definitions/ConservationStatus"
          conservation_statuses:
            type: array
            items:
                $ref: "#/definitions/TaxonConservationStatus"
          default_photo:
            $ref: "#/definitions/TaxonPhoto"
          establishment_means:
            $ref: "#/definitions/EstablishmentMeans"
          observations_count:
            type: integer
          preferred_establishment_means:
            type: string
  Sound:
    type: object
    properties:
      id:
        type: integer
      attribution:
        type: string
      license_code:
        type: string
  TaxonPhoto:
    allOf:
      - $ref: "#/definitions/Photo"
      - type: object
        properties:
          medium_url:
            type: string
          square_url:
            type: string
  User:
    type: object
    properties:
      id:
        type: integer
      icon_content_type:
        type: string
      icon_file_name:
        type: string
      icon:
        type: string
      icon_url:
        type: string
      login:
        type: string
      name:
        type: string
  # Responses
  MessagesResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: "#/definitions/Message"
  NearbyPlacesResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: object
            properties:
              standard:
                type: array
                items:
                  $ref: "#/definitions/ShowPlace"
              community:
                type: array
                items:
                  $ref: "#/definitions/ShowPlace"
  ObservationsResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: "#/definitions/Observation"
  ObservationsShowResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: "#/definitions/ShowObservation"
  UserCountsResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: array
            items:
              type: object
              properties:
                count:
                  type: integer
                user:
                  $ref: "#/definitions/User"
  ObservationsObserversResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: array
            items:
              type: object
              properties:
                observation_count:
                  type: integer
                species_count:
                  type: integer
                user:
                  $ref: "#/definitions/User"
  SpeciesCountsResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: array
            items:
              type: object
              properties:
                count:
                  type: integer
                taxon:
                  $ref: "#/definitions/ShowTaxon"
  PlacesCountsResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: array
            items:
              type: object
              properties:
                count:
                  type: integer
                place:
                  $ref: "#/definitions/CorePlace"
  PlacesResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: "#/definitions/ShowPlace"
  ProjectMembersResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: "#/definitions/ProjectMember"
  ProjectsResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: "#/definitions/Project"
  TaxaAutocompleteResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: "#/definitions/AutocompleteTaxon"
  TaxaShowResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: "#/definitions/ShowTaxon"
  UTFGridResponse:
    properties:
      grid:
        type: array
        items:
          type: string
      keys:
        type: array
        items:
          type: string
      data:
        type: object
  IdentificationsResponse:
    allOf:
      - $ref: "#/definitions/BaseResponse"
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: "#/definitions/Identification"
  # Error
  Error:
    type: object
    properties:
      code:
        type: integer
      message:
        type: string