iNaturalist Places API

openapi: 3.2.0
info:
  title: iNaturalist Places API
  description: '# https://api.inaturalist.org/v1/


    iNaturalist 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.'
  version: 1.3.0
servers:
- url: /v1
tags:
- name: Places
  description: Search and fetch
paths:
  /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: '#/components/parameters/path_multi_id_or_slug'
      - name: admin_level
        in: query
        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)'
        schema:
          type: array
          items:
            type: integer
          enum:
          - -10
          - 0
          - 10
          - 20
          - 30
          - 100
      tags:
      - Places
      responses:
        '200':
          description: 'Returns an object with metadata and an results array of places

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlacesResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getPlacesById
      x-operation-id-source: derived
  /places/autocomplete:
    get:
      summary: Place Autocomplete
      description: 'Given an string, returns places with names starting with the search

        term.'
      parameters:
      - $ref: '#/components/parameters/autocomplete_q'
      - name: order_by
        in: query
        description: Sort field
        schema:
          type: string
          enum:
          - area
      tags:
      - Places
      responses:
        '200':
          description: 'Returns an object with metadata and an results array of places

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlacesResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getPlacesAutocomplete
      x-operation-id-source: derived
  /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: '#/components/parameters/nelat_required'
      - $ref: '#/components/parameters/nelng_required'
      - $ref: '#/components/parameters/swlat_required'
      - $ref: '#/components/parameters/swlng_required'
      - name: name
        in: query
        description: Name must match this value
        schema:
          type: string
      - $ref: '#/components/parameters/per_page'
      tags:
      - Places
      responses:
        '200':
          description: 'Returns an object with metadata and an results object containing

            `standard` and `community` places

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NearbyPlacesResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getPlacesNearby
      x-operation-id-source: derived
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
    swlat_required:
      name: swlat
      in: query
      required: true
      description: 'Must be nearby this bounding box (*nelat, *nelng, *swlat, *swlng)

        '
      schema:
        type: number
        format: double
    nelng_required:
      name: nelng
      in: query
      required: true
      description: 'Must be nearby this bounding box (*nelat, *nelng, *swlat, *swlng)

        '
      schema:
        type: number
        format: double
    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
    swlng_required:
      name: swlng
      in: query
      required: true
      description: 'Must be nearby this bounding box (*nelat, *nelng, *swlat, *swlng)

        '
      schema:
        type: number
        format: double
    nelat_required:
      name: nelat
      in: query
      required: true
      description: 'Must be nearby this bounding box (*nelat, *nelng, *swlat, *swlng)

        '
      schema:
        type: number
        format: double
    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
  schemas:
    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
    BaseResponse:
      type: object
      properties:
        total_results:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
    PlacesResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResponse'
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: '#/components/schemas/ShowPlace'
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    NearbyPlacesResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResponse'
      - required:
        - results
        properties:
          results:
            type: object
            properties:
              standard:
                type: array
                items:
                  $ref: '#/components/schemas/ShowPlace'
              community:
                type: array
                items:
                  $ref: '#/components/schemas/ShowPlace'
    CorePlace:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        display_name:
          type: string
    ShowPlace:
      allOf:
      - $ref: '#/components/schemas/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: '#/components/schemas/PolygonGeoJson'
          location:
            type: string
            description: in the format "lat,lng"
          name:
            type: string
          place_type:
            type: integer
  securitySchemes:
    api_token:
      type: apiKey
      name: Authorization
      in: header