NAV navbar
logo

TaxonWorks API Documentation

version v1
baseUri https://{host}/api/{version}
protocols HTTPS
mediaType application/json

Introduction

This is the documentation for external TaxonWorks API endpoints. Documentation source is at https://github.com/SpeciesFileGroup/taxonworks_api. In brief this allows users to access data curated in a copy of TaxonWorks via a user or project (anonymous) level token.

Servers with live APIs

Each instance of TaxonWorks serves its own API. Add your instance to this list with a pull request.

Roadmap

Our approach:

  • v1 (current)
    • Goal is to expose existing inernal endpoints that the application is built off
    • Endpoints are practical, in that they are nearly being used in interfaces, but not necessarily optimized
    • Largely JSON based, and are derived from Rails conventions
  • v2 (planned)
    • Optimize existing routes, remove nestedness were it makes sense
    • Increase standardization across endpoints of traits (params)
    • Explore delayed responses/ticketing system for long running queries
  • v3 (planned)
    • Integrate caching other optimizations optimization
    • Perhaps move to a fully cached solution, using GraphQL
    • May move cache to a graph DB or other flattened indexer

Running an api-console

This both lets you read the API documentation and experiment directly therein against a local rails server (localhost:3000).

You must have a TaxonWorks instance running at localhost:3000 (rails s, see install_taxonworks) before sending API requests though the console.

Use npm install if you haven't already. Then just run npm start -- --open (-- --open is optional, it will make your browser open the URL the console is being served from).

Once it is ready to explore you should see something like this:

$ npm start -- --open

(OUTPUT OMITTED)

API console build ready.
Thanks for using our API tools!

Files in this directory are available under the following URLs
      applications: http://127.0.0.1:8081

NOTE: It might display a white screen when the browser opens the URL (specially true with Firefox, Chrome seems inmune to this problem). Refresh a few times until it shows the documentation.

Other endpoints

From your terminal withing the source directory (not this repo) use rake routes to get a list of all endpoints. Endpoints are defined as Rails routes in /config/routes/api*.

Types

TaxonNameItem


Properties

id
TaxonName instance identifier

PropertyValue
requiredtrue
typenumber
examples25225

name
The fully latinized string (monomimial) of a code governed taxonomic biological name not applicable for Combinations, they are derived from their pieces.

PropertyValue
requiredtrue
typestring
examplesasymmetricus

parent_id
The id of the parent taxon. The parent child relationship is exclusively organizational. All statuses and relationships of a taxon name must be explicitly defined via taxon name relationships or classifications. The parent of a taxon name can be thought of as "the place where you'd find this name in a hierarchy if you knew literally *nothing* else about that name." In practice read each monomial in the name (protonym or combination) from right to left, the parent is the parent of the last monomial read. There are 3 simple rules for determening the parent of a Protonym or Combination: 1) the parent must always be at least one rank higher than the target names rank 2) the parent of a synonym (any sense) is the parent of the synonym's valid name 3) the parent of a combination is the parent of the highest ranked monomial in the epithet (almost always the parent of the genus)

PropertyValue
requiredtrue
typeinteger
examples2

year_of_publication
Sensu ICZN - the 4 digit year when this name was published, i.e. made available. Not the publishers date stamped on the title page, but the actual date of publication. Precedence for taxon name publication year is TaxonName#year_of_publication, Source#year, Source#stated_year.

PropertyValue
requiredtrue
typeinteger
examplesnil

verbatim_author
The verbatim author string as provided ? is not post-filled in when Source is referenced !?

PropertyValue
requiredtrue
typestring

rank_string
Rank (Kindom, Phylum...) as a string, like {NomenclaturalRank::Iczn::SpeciesGroup::Species}

PropertyValue
requiredtrue
typestring

type
The subclass of this taxon name, e.g. Protonym or Combination.

PropertyValue
requiredtrue
typestring

masculine_name
Species name which are adjective or participle change depending on the gender of the genus. 3 fields provide alternative species spelling. The part_of_speech is designated as a taxon_name_classification. The gender of a genus also designated as a taxon_name_classification.

PropertyValue
requiredtrue
typestring

feminine_name
Species name which are adjective or participle change depending on the gender of the genus. 3 fields provide alternative species spelling. The part_of_speech is designated as a taxon_name_classification. The gender of a genus also designated as a taxon_name_classification.

PropertyValue
requiredtrue
typestring

neuter_name
Species name which are adjective or participle change depending on the gender of the genus. 3 fields provide alternative species spelling. The part_of_speech is designated as a taxon_name_classification. The gender of a genus also designated as a taxon_name_classification.

PropertyValue
requiredtrue
typestring

project_id
The project ID

PropertyValue
requiredtrue
typeinteger

verbatim_name
A representation of what the combination (fully spelled out) or protonym (monomial) *looked like* in its originating publication. The sole purpose of this string is to represent visual differences from what is recorded in the latinized version of the name (Protonym#name, Combination#cached) from what was originally transcribed. This string should NOT include the author year (see verbatim_author and year_of_publication for those data).

PropertyValue
requiredtrue
typestring

etymology
The derivation and history of the name in written form.

PropertyValue
requiredtrue
typestring

cached
Genus-species combination for genus and lower, monomial for higher. The string has NO html, and no author/year.

PropertyValue
requiredtrue
typestring

cached_html
As in `cached` but with tags.

PropertyValue
requiredtrue
typestring

cached_author_year
Author and year string with parentheses where necessary, i.e. with context of present placement for ICZN.

PropertyValue
requiredtrue
typeunion

nomenclatural_code
The name of the nomenclatural code, as a short symbol (:iczn, :icn), or nil

PropertyValue
requiredtrue
typeunion

name_string
The current name/combination with author year, without HTML.

PropertyValue
requiredtrue
typestring

original_combination
The name in original combination, with author year, with HTML.

PropertyValue
requiredtrue
typestring

TYPE DEFINITION

{
  "name": "TaxonNameItem",
  "type": "object",
  "properties": [
    {
      "type": "number",
      "name": "id",
      "displayName": "id",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "TaxonName instance identifier",
      "examples": [
        {
          "value": "25225",
          "strict": true,
          "name": null,
          "structuredValue": 25225
        }
      ],
      "key": "id"
    },
    {
      "type": "string",
      "name": "name",
      "displayName": "name",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The fully latinized string (monomimial) of a code governed taxonomic biological name not \napplicable for Combinations, they are derived from their pieces.\n",
      "examples": [
        {
          "value": "asymmetricus",
          "strict": true,
          "name": null,
          "structuredValue": "asymmetricus"
        }
      ],
      "key": "name"
    },
    {
      "type": "integer",
      "name": "parent_id",
      "displayName": "parent_id",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The id of the parent taxon. The parent child relationship is exclusively organizational. All statuses and relationships\nof a taxon name must be explicitly defined via taxon name relationships or classifications. The parent of a taxon name\ncan be thought of as  \"the place where you'd find this name in a hierarchy if you knew literally *nothing* else about that name.\"\nIn practice read each monomial in the name (protonym or combination) from right to left, the parent is the parent of the last monomial read.\nThere are 3 simple rules for determening the parent of a Protonym or Combination:\n  1) the parent must always be at least one rank higher than the target names rank\n  2) the parent of a synonym (any sense) is the parent of the synonym's valid name\n  3) the parent of a combination is the parent of the highest ranked monomial in the epithet (almost always the parent of the genus)\n",
      "examples": [
        {
          "value": "2",
          "strict": true,
          "name": null,
          "structuredValue": 2
        }
      ],
      "key": "parent_id"
    },
    {
      "type": "integer",
      "name": "year_of_publication",
      "displayName": "year_of_publication",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Sensu ICZN - the 4 digit year when this name was published, i.e. made available. Not the publishers date stamped on the title page,\nbut the actual date of publication. Precedence for taxon name publication year is TaxonName#year_of_publication, Source#year, Source#stated_year.\n",
      "examples": [
        {
          "value": "nil",
          "strict": true,
          "name": null,
          "structuredValue": "nil"
        }
      ],
      "key": "year_of_publication"
    },
    {
      "type": "string",
      "name": "verbatim_author",
      "displayName": "verbatim_author",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The verbatim author string as provided ? is not post-filled in when Source is referenced !?\n",
      "key": "verbatim_author"
    },
    {
      "type": "string",
      "name": "rank_string",
      "displayName": "rank_string",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Rank (Kindom, Phylum...) as a string, like {NomenclaturalRank::Iczn::SpeciesGroup::Species}\n",
      "key": "rank_string"
    },
    {
      "type": "string",
      "name": "type",
      "displayName": "type",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The subclass of this taxon name, e.g. Protonym or Combination.\n",
      "key": "type"
    },
    {
      "type": "string",
      "name": "masculine_name",
      "displayName": "masculine_name",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Species name which are adjective or participle change depending on the gender of the genus.\n3 fields provide alternative species spelling. The part_of_speech is designated as a taxon_name_classification.\nThe gender of a genus also designated as a taxon_name_classification.\n",
      "key": "masculine_name"
    },
    {
      "type": "string",
      "name": "feminine_name",
      "displayName": "feminine_name",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Species name which are adjective or participle change depending on the gender of the genus.\n3 fields provide alternative species spelling. The part_of_speech is designated as a taxon_name_classification.\nThe gender of a genus also designated as a taxon_name_classification.\n",
      "key": "feminine_name"
    },
    {
      "type": "string",
      "name": "neuter_name",
      "displayName": "neuter_name",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Species name which are adjective or participle change depending on the gender of the genus.\n3 fields provide alternative species spelling. The part_of_speech is designated as a taxon_name_classification.\nThe gender of a genus also designated as a taxon_name_classification.\n",
      "key": "neuter_name"
    },
    {
      "type": "integer",
      "name": "project_id",
      "displayName": "project_id",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The project ID\n",
      "key": "project_id"
    },
    {
      "type": "string",
      "name": "verbatim_name",
      "displayName": "verbatim_name",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "A representation of what the combination (fully spelled out) or protonym (monomial) *looked like* in its originating publication.\nThe sole purpose of this string is to represent visual differences from what is recorded in the\nlatinized version of the name (Protonym#name, Combination#cached) from what was originally transcribed.\nThis string should NOT include the author year (see verbatim_author and year_of_publication for those data).\n",
      "key": "verbatim_name"
    },
    {
      "type": "string",
      "name": "etymology",
      "displayName": "etymology",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The derivation and history of the name in written form.\n",
      "key": "etymology"
    },
    {
      "type": "string",
      "name": "cached",
      "displayName": "cached",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Genus-species combination for genus and lower, monomial for higher. The string has NO html, and no author/year.\n",
      "key": "cached"
    },
    {
      "type": "string",
      "name": "cached_html",
      "displayName": "cached_html",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "As in `cached` but with <i></i> tags.\n",
      "key": "cached_html"
    },
    {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "nil"
        }
      ],
      "type": "union",
      "name": "cached_author_year",
      "displayName": "cached_author_year",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Author and year string with parentheses where necessary, i.e. with context of present placement for ICZN.\n",
      "fixedFacets": {
        "description": "Author and year string with parentheses where necessary, i.e. with context of present placement for ICZN.\n"
      },
      "key": "cached_author_year"
    },
    {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "nil"
        }
      ],
      "type": "union",
      "name": "nomenclatural_code",
      "displayName": "nomenclatural_code",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The name of the nomenclatural code, as a short symbol (:iczn, :icn), or nil\n",
      "fixedFacets": {
        "description": "The name of the nomenclatural code, as a short symbol (:iczn, :icn), or nil\n"
      },
      "key": "nomenclatural_code"
    },
    {
      "type": "string",
      "name": "name_string",
      "displayName": "name_string",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The current name/combination with author year, without HTML.\n",
      "key": "name_string"
    },
    {
      "type": "string",
      "name": "original_combination",
      "displayName": "original_combination",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The name in original combination, with author year, with HTML.\n",
      "key": "original_combination"
    }
  ]
}

TaxonNameAutocompleteItem


Properties

id
TaxonName instance identifier

PropertyValue
requiredtrue
typenumber
examples11877

label
Plaintext label for the taxon name comprised of both scientific name and authorship.

PropertyValue
requiredtrue
typestring
examplesJivarus Giglio-Tos, 1898

label_html
HTML-formatted label for the taxon name comprised of both scientific name and authorship.

PropertyValue
requiredtrue
typestring
examples Jivarus Giglio-Tos, 1898     

TYPE DEFINITION

{
  "name": "TaxonNameAutocompleteItem",
  "type": "object",
  "properties": [
    {
      "type": "number",
      "name": "id",
      "displayName": "id",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "TaxonName instance identifier",
      "examples": [
        {
          "value": "11877",
          "strict": true,
          "name": null,
          "structuredValue": 11877
        }
      ],
      "key": "id"
    },
    {
      "type": "string",
      "name": "label",
      "displayName": "label",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Plaintext label for the taxon name comprised of both scientific name and authorship.\n",
      "examples": [
        {
          "value": "Jivarus Giglio-Tos, 1898",
          "strict": true,
          "name": null,
          "structuredValue": "Jivarus Giglio-Tos, 1898"
        }
      ],
      "key": "label"
    },
    {
      "type": "string",
      "name": "label_html",
      "displayName": "label_html",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "HTML-formatted label for the taxon name comprised of both scientific name and authorship.\n",
      "examples": [
        {
          "value": "<span class=\"klass\">\n  <i><mark>Jivarus</mark></i> Giglio-Tos, 1898</span>&nbsp;\n  <span class=\"feedback feedback-info feedback-thin\">genus</span>&nbsp;\n  <span class=\"feedback feedback-secondary feedback-thin\">Jivarini</span>&nbsp;\n  <span class=\"feedback feedback-notice feedback-thin\">Jivarus\n</span>\n",
          "strict": true,
          "name": null,
          "structuredValue": "<span class=\"klass\">\n  <i><mark>Jivarus</mark></i> Giglio-Tos, 1898</span>&nbsp;\n  <span class=\"feedback feedback-info feedback-thin\">genus</span>&nbsp;\n  <span class=\"feedback feedback-secondary feedback-thin\">Jivarini</span>&nbsp;\n  <span class=\"feedback feedback-notice feedback-thin\">Jivarus\n</span>\n"
        }
      ],
      "key": "label_html"
    }
  ]
}

/

Base of the API. Includes an index of open projects indexed by project_token.


/ get

GET: /


Possible Responses

200


/ get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/"

RESPONSE BODY

200

{
  "success": true,
  "open_projects": [
    {
      "mFPoRURskHhXu29nbAxoNy": "My TaxonWorks Project"
    }
  ]
}
Type
any

/ping

An open endpoint to test for life.


/ping get

GET: /ping


Possible Responses

200


/ping get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/ping"

RESPONSE BODY

200

{
  "pong": true
}
Type
any

/user_authenticated

A single purpose route to test your User token.


/user_authenticated get

GET: /user_authenticated


Possible Responses

200


/user_authenticated get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/user_authenticated"

RESPONSE BODY

200

{
  "success": true
}
Type
any

/project_authenticated

A single purpose route to test your Project token.


/project_authenticated get

GET: /project_authenticated


Query Parameters

project_token
A project (not User) token indicating the target project. Don't use together with a user token.

PropertyValue
requiredfalse
typestring
examplesrIO2oWS603c5W5laQ8ornn

Possible Responses

200


/project_authenticated get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/project_authenticated?project_token=rIO2oWS603c5W5laQ8ornn"

RESPONSE BODY

200

{
  "success": true
}
Type
any

/both_authenticated

A single purpose route to test both User and Project tokens.


/both_authenticated get

GET: /both_authenticated


Header Parameters

Authorization
API access token. Do not use with "token" query string parameter.

PropertyValue
requiredfalse
typestring
examplesToken eUUB4dQCCWlLGzksimEqNQ

Query Parameters

token
API access token. Do not use together with the "Authorization" header.

PropertyValue
requiredfalse
typestring
exampleseUUB4dQCCWlLGzksimEqNQ

project_token
A project (not User) token indicating the target project. Don't use together with a user token.

PropertyValue
requiredfalse
typestring
examplesrIO2oWS603c5W5laQ8ornn

Possible Responses

200


/both_authenticated get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/both_authenticated?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE BODY

200

{
  "success": true
}
Type
any

/otus

See Overview at http://rdoc.taxonworks.org/Otu.html


/otus get

GET: /otus

Get all otus, optionally filtered


Header Parameters

Authorization
API access token. Do not use with "token" query string parameter.

PropertyValue
requiredfalse
typestring
examplesToken eUUB4dQCCWlLGzksimEqNQ

Query Parameters

token
API access token. Do not use together with the "Authorization" header.

PropertyValue
requiredfalse
typestring
exampleseUUB4dQCCWlLGzksimEqNQ

project_token
A project (not User) token indicating the target project. Don't use together with a user token.

PropertyValue
requiredfalse
typestring
examplesrIO2oWS603c5W5laQ8ornn

/otus get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/otus?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/taxon_names

See Overview at http://rdoc.taxonworks.org/TaxonName.html


/taxon_names get

GET: /taxon_names

Get all taxon_names, optionally filtered


Header Parameters

Authorization
API access token. Do not use with "token" query string parameter.

PropertyValue
requiredfalse
typestring
examplesToken eUUB4dQCCWlLGzksimEqNQ

Query Parameters

project_id
Project identifier. In the absence of a project token you must provide this parameter.

PropertyValue
requiredfalse
typeinteger
examples1

name
Filter to apply on full taxon name (`cached` property). Matching is case insensitive. See also `exact`.

PropertyValue
requiredfalse
typestring
examplesAus

author
Filter by authors (inside `cached_author_year` property). Matching is case insensitive. Use "&" for "and". See also `exact`.

PropertyValue
requiredfalse
typestring
examplesSmith & Johnson, 2019

year
Filter by authority year (inside `cached_author_year` property). Format is 'YYYY'.

PropertyValue
requiredfalse
typestring
examples2019

exact
True if filter matching must be exact, false if partial matches are allowed.

PropertyValue
requiredfalse
typeboolean
examplestrue

updated_since
Names updated (modified_at property) since this datetime.

PropertyValue
requiredfalse
typedatetime
examples2019-05-20T13:30:00

validity
Filter by validity. True if only valid, false if only invalid, nil if both

PropertyValue
requiredfalse
typestring | nil
examplestrue

parent_id[]
Filter by all children of these parents. Filter includes supplied parents.

PropertyValue
requiredfalse
typearray
examples[ 1, 5 ]

descendants
When set to `true` and `parent_id` filter criterion is used, descendants of parents are included as well.

PropertyValue
requiredfalse
typeboolean
examplestrue

nomenclature_group[]
Filter by nomenclature group.

PropertyValue
requiredfalse
typearray
examples[ "Genus", "Species" ]

nomenclature_code[]
Filter by nomenclature code.

PropertyValue
requiredfalse
typearray
examples[ "ICZN", "ICBN" ]

taxon_name_relationship_type[]
Filter by names having relationships of these types

PropertyValue
requiredfalse
typearray
examples[ "TaxonNameRelationship::Iczn::Invalidating" ]

leaves
If 'true' filters by names having no descendents or with descendants if 'false'.

PropertyValue
requiredfalse
typeboolean | nil
examplestrue

page
The page of taxon_names result set to retrieve.

PropertyValue
requiredfalse
typeinteger
examples5

per
The number of taxon_names per page.

PropertyValue
requiredfalse
typeinteger
examples10

token
API access token. Do not use together with the "Authorization" header.

PropertyValue
requiredfalse
typestring
exampleseUUB4dQCCWlLGzksimEqNQ

project_token
A project (not User) token indicating the target project. Don't use together with a user token.

PropertyValue
requiredfalse
typestring
examplesrIO2oWS603c5W5laQ8ornn

Response Headers

Pagination-Total
Total number of taxon_names in result set.

PropertyValue
requiredtrue
typeinteger
examples30034

Pagination-Total-Pages
Total number of pages for result set.

PropertyValue
requiredtrue
typeinteger
examples300

Pagination-Page
Page number of result set.

PropertyValue
requiredtrue
typeinteger
examples5

Pagination-Per-Page
Number of taxon_names per Page.

PropertyValue
requiredtrue
typeinteger
examples100

Pagination-Previous-Page
Previous page number.

PropertyValue
requiredtrue
typeinteger
examples4

Pagination-Next-Page
Next page number.

PropertyValue
requiredtrue
typeinteger
examples6

Possible Responses

200


/taxon_names get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_names?project_id=1&name=Aus&author=Smith & Johnson, 2019&year=2019&exact=true&updated_since=2019-05-20T13:30:00&validity=true&parent_id[]=[
  1,
  5
]&descendants=true&nomenclature_group[]=[
  "Genus",
  "Species"
]&nomenclature_code[]=[
  "ICZN",
  "ICBN"
]&taxon_name_relationship_type[]=[
  "TaxonNameRelationship::Iczn::Invalidating"
]&leaves=true&page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Total: 30034
Pagination-Total-Pages: 300
Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6

RESPONSE BODY

200

[
  {
    "id": 25225,
    "name": "asymmetricus",
    "parent_id": 25219,
    "cached": "Spiraphonus asymmetricus",
    "cached_html": "\u003ci\u003eSpiraphonus asymmetricus\u003c/i\u003e",
    "feminine_name": null,
    "masculine_name": null,
    "neuter_name": null,
    "cached_author_year": "Gorochov, 2010",
    "etymology": null,
    "year_of_publication": null,
    "verbatim_author": null,
    "rank": "species",
    "rank_string": "NomenclaturalRank::Iczn::SpeciesGroup::Species",
    "type": "Protonym",
    "created_by_id": 5,
    "updated_by_id": 24,
    "project_id": 2,
    "cached_valid_taxon_name_id": 25225,
    "cached_original_combination": "Spiraphonus asymmetricus",
    "cached_original_combination_html": "\u003ci\u003eSpiraphonus asymmetricus\u003c/i\u003e",
    "cached_secondary_homonym": "Spiraphonus asymmetricus",
    "cached_primary_homonym": "Spiraphonus asymmetricus",
    "created_at": "2013-02-12T18:23:00.000Z",
    "updated_at": "2019-03-12T22:57:30.813Z",
    "nomenclatural_code": "iczn",
    "verbatim_name": null,
    "name_string": "Spiraphonus asymmetricus Gorochov, 2010",
    "original_combination": "\u003ci\u003eSpiraphonus asymmetricus\u003c/i\u003e Gorochov, 2010"
  }
]
Type
array


/autocomplete get

GET: /taxon_names/autocomplete

Returns a single TaxonName instance with related data included.


Header Parameters

Authorization
API access token. Do not use with "token" query string parameter.

PropertyValue
requiredfalse
typestring
examplesToken eUUB4dQCCWlLGzksimEqNQ

Query Parameters

project_id
Project identifier. In the absence of a project token you must provide this parameter.

PropertyValue
requiredfalse
typeinteger
examples1

term
The search term by which names will be filtered.

PropertyValue
requiredtrue
typestring
examplesJivarus

type[]
The type of TaxonName (e.g. Protonym, Combination).

PropertyValue
requiredfalse
typearray
examples[ "Combination", "Hybrid" ]

exact
If true TaxonName.name must match the search term exactly to be returned (i.e. no fuzzy matching)

PropertyValue
requiredfalse
typeboolean
examplestrue

valid
Filter by validity. True if only valid, false if only invalid, nil if both

PropertyValue
requiredfalse
typestring | nil
examplestrue

parent_id[]
Filter by all children of these parents. Filter includes supplied parents.

PropertyValue
requiredfalse
typearray
examples[ 1, 5 ]

nomenclature_group[]
Filter by nomenclature group.

PropertyValue
requiredfalse
typearray
examples[ "Genus", "Species" ]

no_leaves
If 'true' names with no children will be excluded.

PropertyValue
requiredfalse
typeboolean
examplestrue

token
API access token. Do not use together with the "Authorization" header.

PropertyValue
requiredfalse
typestring
exampleseUUB4dQCCWlLGzksimEqNQ

project_token
A project (not User) token indicating the target project. Don't use together with a user token.

PropertyValue
requiredfalse
typestring
examplesrIO2oWS603c5W5laQ8ornn

Possible Responses

200


/autocomplete get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_names/autocomplete?project_id=1&term=Jivarus&type[]=[
  "Combination",
  "Hybrid"
]&exact=true&valid=true&parent_id[]=[
  1,
  5
]&nomenclature_group[]=[
  "Genus",
  "Species"
]&no_leaves=true&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE BODY

200

[
  {
    "id": 11877,
    "label": "Jivarus Giglio-Tos, 1898",
    "label_html": "\u003cspan class=\"klass\"\u003e\u003ci\u003e\u003cmark\u003eJivarus\u003c/mark\u003e\u003c/i\u003e Giglio-Tos, 1898\u003c/span\u003e\u0026nbsp;\u003cspan class=\"feedback feedback-info feedback-thin\"\u003egenus\u003c/span\u003e\u0026nbsp;\u003cspan class=\"feedback feedback-secondary feedback-thin\"\u003eJivarini\u003c/span\u003e\u0026nbsp;\u003cspan class=\"feedback feedback-notice feedback-thin\"\u003eJivarus\u003c/span\u003e"
  },
  {
    "id": 11888,
    "label": "Jivarus cohni Ronderos, 1979",
    "label_html": "\u003cspan class=\"klass\"\u003e\u003ci\u003e\u003cmark\u003eJivarus\u003c/mark\u003e cohni\u003c/i\u003e Ronderos, 1979\u003c/span\u003e\u0026nbsp;\u003cspan class=\"feedback feedback-info feedback-thin\"\u003especies\u003c/span\u003e\u0026nbsp;\u003cspan class=\"feedback feedback-secondary feedback-thin\"\u003e\u003ci\u003eJivarus\u003c/i\u003e\u003c/span\u003e\u0026nbsp;\u003cspan class=\"feedback feedback-notice feedback-thin\"\u003eJivarus cohni\u003c/span\u003e"
  }
]
Type
array


/{id} get

GET: /taxon_names/{id}

Returns TaxonName instance data.


URI Parameters

id

PropertyValue
requiredtrue
typestring

Header Parameters

Authorization
API access token. Do not use with "token" query string parameter.

PropertyValue
requiredfalse
typestring
examplesToken eUUB4dQCCWlLGzksimEqNQ

Query Parameters

project_id
Project identifier. In the absence of a project token you must provide this parameter.

PropertyValue
requiredfalse
typeinteger
examples1

token
API access token. Do not use together with the "Authorization" header.

PropertyValue
requiredfalse
typestring
exampleseUUB4dQCCWlLGzksimEqNQ

project_token
A project (not User) token indicating the target project. Don't use together with a user token.

PropertyValue
requiredfalse
typestring
examplesrIO2oWS603c5W5laQ8ornn

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_names/{id}?project_id=1&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ