iNaturalist Projects API

openapi: 3.2.0
info:
  title: iNaturalist Annotations Projects 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
servers:
- url: /v1
tags:
- name: Projects
  description: Search and fetch projects and members
paths:
  /projects:
    get:
      summary: Project Search
      description: 'Given zero to many of following parameters, returns projects

        matching the search criteria

        '
      parameters:
      - $ref: '#/components/parameters/autocomplete_q_not_required'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/not_id'
      - $ref: '#/components/parameters/lat'
      - $ref: '#/components/parameters/lng'
      - $ref: '#/components/parameters/associated_place_id'
      - $ref: '#/components/parameters/projects_radius'
      - $ref: '#/components/parameters/featured'
      - $ref: '#/components/parameters/noteworthy'
      - $ref: '#/components/parameters/projects_site_id'
      - $ref: '#/components/parameters/rule_details'
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/member_id'
      - $ref: '#/components/parameters/has_params'
      - $ref: '#/components/parameters/has_posts'
      - $ref: '#/components/parameters/per_page'
      - $ref: '#/components/parameters/projects_order_by'
      tags:
      - Projects
      responses:
        '200':
          description: 'Returns an object with metadata and an array of projects

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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: '#/components/parameters/path_multi_id_or_slug'
      - $ref: '#/components/parameters/rule_details'
      tags:
      - Projects
      responses:
        '200':
          description: 'Returns an object with metadata and an array of projects

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /projects/{id}/join:
    post:
      summary: Projects Join
      description: 'Join a project

        '
      parameters:
      - $ref: '#/components/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: '#/components/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: '#/components/parameters/path_id'
      - name: role
        in: query
        description: Membership role
        schema:
          type: string
          enum:
          - curator
          - manager
      - $ref: '#/components/parameters/skip_counts'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      tags:
      - Projects
      responses:
        '200':
          description: 'Returns an object with metadata and an results array of projects

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectMembersResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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: '#/components/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: '#/components/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
      parameters:
      - $ref: '#/components/parameters/path_id'
      tags:
      - Projects
      security:
      - api_token: []
      responses:
        '200':
          description: OK
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostProjectAdd'
        description: ProjectObservation object
  /projects/{id}/remove:
    delete:
      summary: Project Add
      description: Remove an observation from a project
      parameters:
      - $ref: '#/components/parameters/path_id'
      tags:
      - Projects
      security:
      - api_token: []
      responses:
        '200':
          description: OK
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostProjectAdd'
        description: ProjectObservation object
  /projects/autocomplete:
    get:
      summary: Project Autocomplete
      description: 'Given an string, returns projects with titles starting with the search term

        '
      parameters:
      - $ref: '#/components/parameters/autocomplete_q'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/not_id'
      - $ref: '#/components/parameters/lat'
      - $ref: '#/components/parameters/lng'
      - $ref: '#/components/parameters/associated_place_id'
      - $ref: '#/components/parameters/projects_radius'
      - $ref: '#/components/parameters/featured'
      - $ref: '#/components/parameters/noteworthy'
      - $ref: '#/components/parameters/projects_site_id'
      - $ref: '#/components/parameters/rule_details'
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/member_id'
      - $ref: '#/components/parameters/has_params'
      - $ref: '#/components/parameters/has_posts'
      - $ref: '#/components/parameters/per_page'
      tags:
      - Projects
      responses:
        '200':
          description: 'Returns an object with metadata and an results array of places

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /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: '#/components/parameters/path_id'
      tags:
      - Projects
      security:
      - api_token: []
      responses:
        '200':
          description: OK
components:
  parameters:
    path_multi_id_or_slug:
      name: id
      in: path
      required: true
      description: Must have this ID or slug
      schema:
        type: array
        items:
          type: string
    projects_site_id:
      name: site_id
      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

        '
      schema:
        type: integer
    page:
      name: page
      in: query
      description: Pagination `page` number
      schema:
        type: string
    lng:
      name: lng
      in: query
      description: 'Must be within a {`radius`} kilometer circle around this lat/lng

        (*lat, *lng, radius)

        '
      schema:
        type: number
        format: double
    id:
      name: id
      in: query
      description: Must have this ID
      schema:
        type: array
        items:
          type: string
        minimum: 1
    projects_radius:
      name: radius
      in: query
      description: 'Must be within a {`radius`} kilometer circle around this lat/lng

        (*lat, *lng, radius). Defaults to 500km

        '
      schema:
        type: string
    type:
      name: type
      in: query
      description: Projects must be of this type
      schema:
        type: array
        items:
          type: string
        enum:
        - collection
        - umbrella
    rule_details:
      name: rule_details
      in: query
      description: 'Return more information about project rules, for example return a full

        taxon object instead of simply an ID

        '
      schema:
        type: string
        enum:
        - true
    has_posts:
      name: has_posts
      in: query
      description: Must have posts
      schema:
        type: boolean
    autocomplete_q:
      name: q
      in: query
      required: true
      description: Search by name (must start with this value) or by ID (exact match).
      schema:
        type: string
    skip_counts:
      name: skip_counts
      in: query
      description: 'If counts are not needed, consider setting this to true to save on

        processing time, resulting in faster responses

        '
      schema:
        type: boolean
        default: false
    associated_place_id:
      name: place_id
      in: query
      description: Must be associated with this place
      schema:
        type: array
        items:
          type: string
    projects_order_by:
      name: order_by
      in: query
      description: Sort field
      schema:
        type: string
        enum:
        - recent_posts
        - created
        - updated
        - distance
        - featured
    member_id:
      name: member_id
      in: query
      description: Project must have member with this user ID
      schema:
        type: integer
    has_params:
      name: has_params
      in: query
      description: Must have search parameter requirements
      schema:
        type: boolean
    path_id:
      name: id
      in: path
      required: true
      description: ID of the record
      schema:
        type: integer
    noteworthy:
      name: noteworthy
      in: query
      description: Must be marked noteworthy for the relevant site
      schema:
        type: string
        enum:
        - true
    per_page:
      name: per_page
      in: query
      description: 'Number of results to return in a `page`. The maximum value is generally

        200 unless otherwise noted

        '
      schema:
        type: string
    path_multi_id:
      name: id
      in: path
      required: true
      description: Must have this ID
      schema:
        type: array
        items:
          type: integer
    autocomplete_q_not_required:
      name: q
      in: query
      description: Search by name (must start with this value) or by ID (exact match).
      schema:
        type: string
    featured:
      name: featured
      in: query
      description: Must be marked featured for the relevant site
      schema:
        type: string
        enum:
        - true
    not_id:
      name: not_id
      in: query
      description: Must not have this ID
      schema:
        type: array
        items:
          type: string
        minimum: 1
    lat:
      name: lat
      in: query
      description: 'Must be within a {`radius`} kilometer circle around this lat/lng

        (*lat, *lng, radius)

        '
      schema:
        type: number
        format: double
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    ProjectMembersResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResponse'
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: '#/components/schemas/ProjectMember'
    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: '#/components/schemas/User'
    User:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        id:
          type: integer
        icon:
          type: string
        icon_url:
          type: string
        identifications_count:
          type: integer
        journal_posts_count:
          type: integer
        login:
          type: string
        name:
          type: string
        observations_count:
          type: integer
        orcid:
          type: string
        roles:
          type: array
          items:
            type: string
            enum:
            - admin
            - app owner
            - curator
        site_id:
          type: integer
        species_count:
          type: integer
        spam:
          type: boolean
        suspended:
          type: boolean
    ProjectsResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResponse'
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: '#/components/schemas/Project'
    Project:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        description:
          type: string
        slug:
          type: string
    PostProjectAdd:
      type: object
      properties:
        observation_id:
          type: integer
    BaseResponse:
      type: object
      properties:
        total_results:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
  securitySchemes:
    api_token:
      type: apiKey
      name: Authorization
      in: header