iNaturalist Taxa API

openapi: 3.2.0
info:
  title: iNaturalist Annotations Taxa 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: Taxa
  description: Search and fetch
paths:
  /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: '#/components/parameters/path_multi_id'
      - $ref: '#/components/parameters/rank_level'
      tags:
      - Taxa
      responses:
        '200':
          description: 'Returns an object with metadata and a results array of taxa

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxaShowResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /taxa:
    get:
      summary: Taxon Search
      description: 'Given zero to many of following parameters, returns taxa matching the search criteria

        '
      parameters:
      - $ref: '#/components/parameters/autocomplete_q_not_required'
      - name: is_active
        in: query
        description: Taxon is `active`
        schema:
          type: boolean
      - name: id
        in: query
        description: Comma-separated list of taxon IDs
        schema:
          type: array
          items:
            type: integer
      - $ref: '#/components/parameters/parent_id'
      - $ref: '#/components/parameters/rank'
      - $ref: '#/components/parameters/rank_level'
      - $ref: '#/components/parameters/id_above'
      - $ref: '#/components/parameters/id_below'
      - $ref: '#/components/parameters/per_page'
      - $ref: '#/components/parameters/locale'
      - $ref: '#/components/parameters/preferred_place_id'
      - $ref: '#/components/parameters/only_id'
      - $ref: '#/components/parameters/all_names'
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/taxa_order_by'
      tags:
      - Taxa
      responses:
        '200':
          description: 'Returns an object with search metadata and a results array of taxa

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxaShowResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /taxa/autocomplete:
    get:
      summary: Taxon Autocomplete
      description: 'Given an string, returns taxa with names starting with the search term

        '
      parameters:
      - $ref: '#/components/parameters/autocomplete_q'
      - name: is_active
        in: query
        description: Taxon is `active`
        schema:
          type: boolean
      - $ref: '#/components/parameters/taxa_taxon_id'
      - $ref: '#/components/parameters/rank'
      - $ref: '#/components/parameters/rank_level'
      - name: per_page
        in: query
        description: Number of results to return in a `page`. The maximum value is 30 for this endpoint
        schema:
          type: string
      - $ref: '#/components/parameters/locale'
      - $ref: '#/components/parameters/preferred_place_id'
      - $ref: '#/components/parameters/all_names'
      tags:
      - Taxa
      responses:
        '200':
          description: 'Returns an object with search metadata and a results array of taxa

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxaAutocompleteResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    preferred_place_id:
      name: preferred_place_id
      in: query
      description: 'Place preference for regional taxon common names

        '
      schema:
        type: integer
    id_above:
      name: id_above
      in: query
      description: Must have an ID above this value
      schema:
        type: string
    only_id:
      name: only_id
      in: query
      description: Return only the record IDs
      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
    id_below:
      name: id_below
      in: query
      description: Must have an ID below this value
      schema:
        type: string
    order:
      name: order
      in: query
      description: Sort order
      schema:
        type: string
        enum:
        - desc
        - asc
        default: desc
    parent_id:
      name: parent_id
      in: query
      description: Taxon's parent must have this ID
      schema:
        type: integer
    locale:
      name: locale
      in: query
      description: 'Locale preference for taxon common names

        '
      schema:
        type: string
    rank_level:
      name: rank_level
      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)

        '
      schema:
        type: number
    all_names:
      name: all_names
      in: query
      description: Include all taxon names in the response
      schema:
        type: boolean
    taxa_order_by:
      name: order_by
      in: query
      description: Sort field
      schema:
        type: string
        enum:
        - id
        - created_at
        - observations_count
        default: observations_count
    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
    taxa_taxon_id:
      name: taxon_id
      in: query
      description: Only show taxa with this ID, or its descendants
      schema:
        type: array
        items:
          type: string
        minimum: 1
    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
    rank:
      name: rank
      in: query
      description: Taxon must have this rank
      schema:
        type: array
        items:
          type: string
        enum:
        - stateofmatter
        - kingdom
        - phylum
        - subphylum
        - superclass
        - class
        - subclass
        - superorder
        - order
        - suborder
        - infraorder
        - superfamily
        - epifamily
        - family
        - subfamily
        - supertribe
        - tribe
        - subtribe
        - genus
        - genushybrid
        - species
        - hybrid
        - subspecies
        - variety
        - form
  schemas:
    Color:
      type: object
      properties:
        id:
          type: integer
        value:
          type: string
    Photo:
      type: object
      properties:
        id:
          type: integer
        attribution:
          type: string
        license_code:
          type: string
        url:
          type: string
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          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
    TaxaShowResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResponse'
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: '#/components/schemas/ShowTaxon'
    TaxonConservationStatus:
      allOf:
      - $ref: '#/components/schemas/RawConservationStatus'
      - type: object
        properties:
          place:
            $ref: '#/components/schemas/CorePlace'
    AutocompleteTaxon:
      allOf:
      - $ref: '#/components/schemas/CoreTaxon'
      - type: object
        properties:
          default_photo:
            $ref: '#/components/schemas/TaxonPhoto'
          matched_term:
            type: string
          observations_count:
            type: integer
    ShowTaxon:
      allOf:
      - $ref: '#/components/schemas/CoreTaxon'
      - type: object
        properties:
          ancestor_ids:
            type: array
            items:
              type: integer
          colors:
            type: array
            items:
              $ref: '#/components/schemas/Color'
          conservation_status:
            $ref: '#/components/schemas/ConservationStatus'
          conservation_statuses:
            type: array
            items:
              $ref: '#/components/schemas/TaxonConservationStatus'
          default_photo:
            $ref: '#/components/schemas/TaxonPhoto'
          establishment_means:
            $ref: '#/components/schemas/EstablishmentMeans'
          observations_count:
            type: integer
          preferred_establishment_means:
            type: string
    CorePlace:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        display_name:
          type: string
    EstablishmentMeans:
      type: object
      properties:
        establishment_means:
          type: string
        place:
          $ref: '#/components/schemas/CorePlace'
    ConservationStatus:
      type: object
      properties:
        place_id:
          type: integer
        place:
          $ref: '#/components/schemas/CorePlace'
        status:
          type: string
    TaxonPhoto:
      allOf:
      - $ref: '#/components/schemas/Photo'
      - type: object
        properties:
          medium_url:
            type: string
          square_url:
            type: string
    BaseResponse:
      type: object
      properties:
        total_results:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
    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.

            '
    TaxaAutocompleteResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResponse'
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: '#/components/schemas/AutocompleteTaxon'
  securitySchemes:
    api_token:
      type: apiKey
      name: Authorization
      in: header