iNaturalist API

The iNat REST API is generally for retrieving data from iNaturalist. Data can be retrieved in different formats by appending .[format] to the endpoint, e.g. /observations.json to retrieve observations as JSON.

Contents
 

GET /observations

Primary endpoint for retrieving observations. JSON and ATOM responses are what you'd expect, but DwC is Simple Darin Core, an XML schema for biodiversity data. iNat uses JSON responses internally quite a bit, so it will probably always be the most information-rich. The widget response is a JS snippet that inserts HTML. It should be used with a script tag, e.g.

<script src="http://www.inaturalist.org/observations.widget"></script>

Formats: atom, csv, dwc, json, kml, widget

Params

q
Search query
any string
page
any integer
per_page
1 to 200
order_by
Field to sort by
observed_on
date observed
date_added
date added to iNat
order
Sort order
asc | desc
license
Specify the license users have applied to their observations.
none
No license specified, observer witholds all rights to distribution.
any
Observation licensed, see response for license specified.
CC-BY
Creative Commons Attribution License
CC-BY-NC
Creative Commons Attribution-NonCommercial License
CC-BY-SA
Creative Commons Attribution-ShareAlike License
CC-BY-ND
Creative Commons Attribution-NoDerivs License
CC-BY-NC-SA
Creative Commons Attribution-NonCommercial-ShareAlike License
CC-BY-NC-ND
Creative Commons Attribution-NonCommercial-NoDerivs License
photo_license
Filter by the license of the associated photos.
Same as license param
taxon_id
Filter by iNat taxon ID. Note that this will also select observations of descendant taxa.
valid iNat taxon ID
taxon_name
Filter by iNat taxon name. Note that this will also select observations of descendant taxa. Note that names are not unique, so if the name matches multiple taxa, no observations may be returned.
Name string
iconic_taxa[]
Filter by iconic taxa. Can be used multiple times, e.g. iconic_taxa[]=Fungi&iconic_taxa[]=Mammalia
Plantae | Animalia | Mollusca | Reptilia | Aves | Amphibia | Actinopterygii | Mammalia | Insecta | Arachnida | Fungi | Protozoa | Chromista | unknown
has[]
Catch-all for some boolean selectors. This can be used multiple times, e.g. has[]=photos&has[]=geo
photos
only show observations with photos
geo
only show georeferenced observations
id_please
only show observations in need of ID help
quality_grade
Filter by quality grade
casual | research
out_of_range
Filter by whether or not iNat considers the observation out of range for the associated taxon. This is based on iNat's range data.
true
on
Filter by date string
Date strings in the form yyyy-mm-dd, e.g. 2001-05-02. You can also omit day and/or month, e.g. 2001-05 and 2001
year
Filter by year
any integer
month
Filter by month
1 to 12
day
Filter by day of the month
1 to 31
swlat
Southwest latitude of a bounding box query.
-90 to 90
swlng
Southwest longitude of a bounding box query.
-180 to 180
nelat
Northeast latitude of a bounding box query.
-90 to 90
nelng
Northeast longitude of a bounding box query.
-180 to 180

Example

Request (try it)

/observations.json

Response

[{
    "user_login": "greatjon",
    "place_guess": "San Francisco, San Francisco",
    "location_is_exact": false,
    "quality_grade": "casual",
    "latitude": 37.713539,
    "created_at": "2012-04-10T21:48:25-07:00",
    "timeframe": null,
    "species_guess": "gray wolf",
    "observed_on": "2012-04-10",
    "num_identification_disagreements": 0,
    "delta": true,
    "updated_at": "2012-04-10T21:49:50-07:00",
    "num_identification_agreements": 0,
    "license": null,
    "geoprivacy": null,
    "positional_accuracy": 354,
    "coordinates_obscured": false,
    "taxon_id": 42048,
    "id_please": false,
    "id": 2281,
    "iconic_taxon": {
        "name": "Mammalia",
        "ancestry": "48460/1/2",
        "rank": "class",
        "id": 40151,
        "rank_level": 50,
        "iconic_taxon_name": "Mammalia"
    },
    "time_observed_at_utc": "2012-04-11T04:47:55Z",
    "user_id": 53,
    "time_observed_at": "2012-04-10T21:47:55-07:00",
    "observed_on_string": "Tue Apr 10 2012 21:47:55 GMT-0700 (PDT)",
    "short_description": "",
    "time_zone": "Pacific Time (US & Canada)",
    "out_of_range": null,
    "longitude": -122.340054,
    "description": "",
    "user": {
        "login": "greatjon"
    },
    "positioning_method": null,
    "map_scale": null,
    "photos": [],
    "iconic_taxon_name": "Mammalia",
    "positioning_device": null,
    "iconic_taxon_id": 40151
}]

GET /observations/:username

Just like /observations except filtered by a username.

GET /observations/project/:id

Just like /observations except filtered by a project. :id can be a project ID or slug. CSV response will return some extra project-specific daa.

Formats: atom, csv, json, kml, widget

GET /places

Retrieve information about places.

Formats: json

Params

page
any integer
1
per_page
1 to 200
30
ancestor_id
Filter places by an ancestor place based on place hierarchy. If you wanted to view all places that are a part of California, you would set ancestor_id=14.
Place ID integer
place_type
Type of place to retrieve
Aggregate | Airport | Colloquial | Continent | Country | County | Drainage | Estate | Historical County | Historical State | Historical Town | Intersection | Island | Land Feature | Local Administrative Area | Miscellaneous | Nationality | Open Space | Point of Interest | Region | State | Street | Street | Street Segment | Supername | Town | Undefined | Zone
taxon
Retrieve places with this taxon on their check lists. Can be specified as an ID or a name, though vernacular names may yield unpredictable results. Note that this gets a bit weird for continents, since they don't have check lists: continents will not be returned *unless* place_type=continent.
Taxon ID or name

Example

Request (try it)

/places.json?taxon=Calochortus+tiburonensis&place_type=open+space

Response

[{
    "ancestry": "1/14/2319",
    "check_list_id": 6079,
    "code": null,
    "created_at": "2009-06-29T22:24:50-07:00",
    "display_name": "Ring Mountain Open Space Preserve, CA, US",
    "id": 3104,
    "latitude": "37.9130554199",
    "longitude": "-122.4938278198",
    "name": "Ring Mountain Open Space Preserve",
    "nelat": "37.92107",
    "nelng": "-122.48223",
    "parent_id": 2319,
    "place_type": 100,
    "source_identifier": "Ring Mountain Preserve",
    "source_name": "Ring Mountain Preserve",
    "swlat": "37.90504",
    "swlng": "-122.50542",
    "updated_at": "2012-09-26T03:14:01-07:00",
    "user_id": null,
    "woeid": null,
    "place_type_name": "Open Space"
  }]

Example

Request (try it)

/places.json?place_type=state&q=California

Response

[{
    "ancestry": "1",
    "check_list_id": 312,
    "code": "US-CA",
    "created_at": "2009-06-29T21:46:28-07:00",
    "display_name": "California, US",
    "id": 14,
    "latitude": "37.2691993713",
    "longitude": "-119.3069992065",
    "name": "California",
    "nelat": "42.008804",
    "nelng": "-114.131211",
    "parent_id": 1,
    "place_type": 8,
    "source_identifier": "3195",
    "source_name": "3195",
    "swlat": "32.528832",
    "swlng": "-124.480543",
    "updated_at": "2012-09-26T03:13:52-07:00",
    "user_id": null,
    "woeid": 2347563,
    "place_type_name": "State"
  }, {
    "ancestry": "6793",
    "check_list_id": 7754,
    "code": "MX-BCN",
    "created_at": "2009-10-24T18:01:56-07:00",
    "display_name": "Baja California, MX",
    "id": 7403,
    "latitude": "30.3589992523",
    "longitude": "-114.9445877075",
    "name": "Baja California",
    "nelat": "32.71804",
    "nelng": "-112.4939948948",
    "parent_id": 6793,
    "place_type": 8,
    "source_identifier": "1805",
    "source_name": "1805",
    "swlat": "27.835026736",
    "swlng": "-118.4187830224",
    "updated_at": "2012-09-26T03:14:35-07:00",
    "user_id": null,
    "woeid": 2346265,
    "place_type_name": "State"
  }, {
    "ancestry": "6793",
    "check_list_id": 9190,
    "code": "MX-BCS",
    "created_at": "2010-06-28T12:49:24-07:00",
    "display_name": "Baja California Sur, MX",
    "id": 8501,
    "latitude": "25.4334506989",
    "longitude": "-111.53881073",
    "name": "Baja California Sur",
    "nelat": "28.0027035634",
    "nelng": "-109.362976567",
    "parent_id": 6793,
    "place_type": 8,
    "source_identifier": "1806",
    "source_name": "1806",
    "swlat": "18.2910523956",
    "swlng": "-115.8180955045",
    "updated_at": "2012-09-26T03:14:37-07:00",
    "user_id": null,
    "woeid": 2346266,
    "place_type_name": "State"
  }]

GET /projects

Retrieve information about projects on iNaturalist.

Formats: json

Params

page
Results are returned in pages of 100 projects.
any integer
featured
Select only featured projects. Featured projects are chosen by site admins.
true
latitude
Search for observations within 5 degrees of a given point. Results are ordered by distance from that point. Geographic queries will only return projects that have an observation rule tied to a given place.
-90 to 90
longitude
See latitude.
-180 to 180
source
Find projects by source, usually a URI identifying an external resource from which the project was derived.

Example

Request (try it)

/projects.json?featured=true

Response

[{
    "created_at": "2011-08-12T10:21:28-07:00",
    "created_at_utc": "2011-08-12T17:21:28Z",
    "title": "ASC Pika Project",
    "project_type": "contest",
    "project_observation_rule_terms": "must be on list",
    "updated_at": "2012-04-26T19:38:51-07:00",
    "updated_at_utc": "2012-04-27T02:38:51Z",
    "source_url": "",
    "id": 44,
    "user_id": 477,
    "featured_at": "2012-04-26T19:38:51-07:00",
    "featured_at_utc": "2012-04-27T02:38:51Z",
    "icon_url": "http://www.inaturalist.org/attachments/projects/icons/44/span2/APAlogo.png?1315005828",
    "icon_file_size": 9454,
    "icon_file_name": "APAlogo.png",
    "icon_content_type": "image/png",
    "description": "The goal of this project is to document the persistence or extirpation of American Pika throughout their range for science and conservation. Read our flyer to find out more! According to the pika range map compiled by the IUCN, American pika are thought to occur in two occur in 2 Countries, 12 States (or Canadian Provinces) and 276 Counties (or Canadian Regional Districts). We seek to collect recent observations verifying Pika persistence in each of these places. This project is supported by the North American Pika Consortium, the California Department of Fish and Game, and the Front Range Pika Project.",
    "cached_slug": "asc-pika-project",
    "project_list": {
        "comprehensive": false,
        "place_id": null,
        "created_at": "2011-08-12T12:33:04-07:00",
        "created_at_utc": "2011-08-12T19:33:04Z",
        "title": "American Pika Atlas's Check List",
        "updated_at": "2011-08-12T12:33:04-07:00",
        "project_id": 44,
        "updated_at_utc": "2011-08-12T19:33:04Z",
        "taxon_id": null,
        "id": 52561,
        "user_id": null,
        "last_synced_at": null,
        "description": "Every species observed by members of American Pika Atlas",
        "source_id": null
    },
    "terms": "Please only upload observations if you agree to make them available non-commercial scientific analyses. We will attribute you as the photographer if your photos are used in any published scientific analyses. If possible please include locations, dates, and photos with your observations.",
    "observed_taxa_count": 2,
    "icon_updated_at": "2011-09-02T16:23:48-07:00",
    "rule_place": null,
    "project_observations_count": 12
}]

GET /projects/:id

Retrieve information about a single project. :id is the project ID or slug.

Formats: json

GET /projects/:id?iframe=true

This returns a complete web page without header or footer suitable for use in an IFRAME.

GET /projects/:id/contributors.widget

JS widget snippet of the top contributors to a project.