{"mock":"https://private-anon-64164b2f18-oakparks.apiary-mock.com/v1/","production":"https://api.oakparks.org/v1/","proxy":"https://private-anon-64164b2f18-oakparks.apiary-proxy.com/v1/"}
FORMAT: 1A
HOST: https://api.oakparks.org/v1
# Oakparks
A RESTful JSON api for querying plant data and their properties.
## Taxa (Plants)
The API revolves around [biological taxa](https://en.wikipedia.org/wiki/Taxon). Every plant or plant family is a taxon.
This API allows you to identify the taxon you're looking for through the use of aliases. Once you know your taxon, you can easily get related information, such as its properties, other names, photos, and meta information.
You can also look up taxa by their properties, which makes this API much more useful for the general public, since most would rather choose plants by their properties. A plant's name is only for reference, what matters are its properties.
## Names
Biological names are notoriously difficult to pin-down. For any given plant, there will likely be many more names for it. Plants are rarely referred to by their scientific name in the real world. Even worse, the scientific name is often disputed to begin with.
Having said that, we've done our best to inlcude as many aliases and their taxonomic status as possible. The accepted names used for taxa use the [Catalogue of Life](http://www.catalogueoflife.org/) database.
We've also made it easy to contribute names to taxa through the [alias create method](http://docs.oakparks.apiary.io/#reference/aliases/create-alias/post).
# Group Taxa
## Taxa Collection [/taxa{?page,per_page,rank,tags,q,sort_by,order}]
Find or filter a collection of taxa. May also be used as a quick and simple search. For a more robust search that uses properties, try the <a href="http://docs.oakparks.apiary.io/#reference/taxa/taxa-search/get">/search endpoint.</a>
### GET
+ Parameters
+ q: `cham` (optional,string) - Filter by search query. Will search amongst aliases as well.
+ page: `1` (optional, number) - The pagination number.
+ per_page: `20` (optional, number) - The number of taxa to return per request. Max 100.
+ order: `-rank` (optional,string) - Sort an attribute either by default ascendeing or add a "-" to descend.
+ tags: `annuals,perennials` (optional,string) - Comma separated list of tags to filter. Will accept tag name, slug, or id.
+ rank: `species` (optional, Ranks) - Filter results by rank.
+ Response 200 (application/json)
+ Attributes
- data (array[Taxon])
- meta
- pagination (Pagination)
- links (Links)
## Taxon Resource [/taxa/{id}]
This a Taxon resource. This is the core of the API, as everything else revolves around this. Some helpful links to subresources are provided.
### GET
+ Parameters
+ id (enum[string])
ID or Slug
- `n8rxo9rm` - The unique ID
- `lecythis-corrugata-rosea` - The unique slug
+ Response 200 (application/json)
+ Attributes
+ data
+ Include Basic Resource
+ type: `taxon` (string)
+ attributes (Full Taxon)
+ links (object)
- children: `https://api.oakparks.com/v1/taxa/n8rxo9rm/children` (string) - Link to child taxa.
- breadcrumb: `https://api.oakparks.com/v1/taxa/n8rxo9rm/breadcrumb` (string) - Link to the taxon's breadcrumb.
- media: `https://api.oakparks.com/v1/taxa/n8rxo9rm/media` (string) - Link to the taxon's media.
- props: `https://api.oakparks.com/v1/taxa/n8rxo9rm/props` (string) - Link to the taxon's properties.
- aliases: `https://api.oakparks.com/v1/taxa/n8rxo9rm/aliases` (string) - Link to the taxon's aliases.
## Taxa Search [/taxa/search{?q,page,per_page,rank,tags,sort_by,order,props,value}]
This is the advanced taxa search. It's slightly slower, but can be used to find taxa by their properties.
### GET
+ Parameters
+ q: `cham` (optional,string) - Filter by search query. Will search amongst aliases as well.
+ page: `1` (optional, number) - The pagination number.
+ per_page: `20` (optional, number) - The number of taxa to return per request. Max 100.
+ order: `+rank` (optional,string) - Sort an attribute either by descending (-) or ascending (+). Accepts a comma separated list for several attributes.
+ tags: `annuals,perennials` (optional,string) - Comma separated list of tags to filter. Will accept tag name, slug, or id.
+ rank: `species` (optional, Ranks) - Filter results by rank.
+ props: `appearance:color_bloom:fuschia` (optional, string) - Filter taxa by their properties. Takes the format of `element:type:value`. Multiple props are delimited by a comma.
+ Response 200 (application/json)
+ Attributes
- data (array[Taxon])
- meta
- pagination (Pagination)
- links (Links)
## Taxa Children [/taxa/{id}/children{?page,per_page,order,rank}]
Most taxa will have child taxa at various ranks, including species themselves. This will return a collection of direct descendents.
### GET
+ Parameters
+ id (enum[string])
ID or Slug
- `n8rxo9rm` - The unique ID
- `lecythis-corrugata-rosea` - The unique slug
+ rank: `species` - Will only list child taxa of a particular rank. Will throw an error if the rank is greater than or equal to the parent's rank.
+ page: `1` (optional, number) - The pagination number.
+ per_page: `20` (optional, number) - The number of taxa to return per request. Max 100.
+ order: `+rank` (optional,string) - Sort an attribute either by descending (-) or ascending (+). Accepts a comma separated list for several attributes.
+ Response 200 (application/json)
+ Attributes
- data (array[Taxon])
- meta
- pagination (Pagination)
- links (Links)
## Taxa Breadcrumb [/taxa/{id}/breadcrumb{?reverse}]
Taxa have a taxonomic order and thus a breadcrumb of parents. This will list each parent of the taxon in order of their rank. The default order is from highest rank (`Domain`) to the current taxon's rank.
### GET
+ Parameters
+ id: `n8rxo9rm` (enum[string])
ID or Slug
- `n8rxo9rm` - The unique ID
- `lecythis-corrugata-rosea` - The unique slug
+ reverse: `false` (optional, boolean)
List highest to lowest hierarchy
- asc (string) - Display breadcrumb from highest rank to lowest
- desc (string) - Display breadcrumb from lowest rank to highest
+ Response 200 (application/json)
+ Attributes
- data (array[Taxon])
# Group Properties
Most taxa will have properties attached to them. They are organized by element and type. Here, you can find a list of properties and their values for a particular taxon.
An element can be thought of as a category of different property types. For example, the properties: "Blue Shape", and "Fruit Color" would fall under the "Appearance" element.
Properties will return an array of values. Sometimes values are arbitrary, however other times they are predefined. You may get a collection of the possible values through the <a href="http://docs.oakparks.apiary.io/#reference/properties/property-resource">Prop subresource</a>.
## Properties Collection [/taxa/{id}/props{?element,type}]
### GET
+ Parameters
+ id (enum[string])
ID or Slug
- `n8rxo9rm` - The unique ID
- `lecythis-corrugata-rosea` - The unique slug
+ Response 200 (application/json)
+ Attributes
- data (array[Property])
## Property Resource [/props/{id}]
Every property belongs to a taxon. Here, you can get the full data for a property, including some meta information.
### GET
+ Parameters
+ id: `n8rxo9rm` (string) - The unique ID
+ Response 200 (application/json)
+ Attributes
- data (Full Property)
## Types & Elements [/props/types]
Retrieve a list of the different kinds of elements and property types.
### GET
+ Response 200 (application/json)
+ Attributes
- data (array[Type])
# Group Media
## Media Collection [/taxa/{id}/media{?page,per_page,order}]
### GET
+ Parameters
+ id (enum[string])
ID or Slug
- `n8rxo9rm` - The unique ID
- `lecythis-corrugata-rosea` - The unique slug
+ page: `1` (optional, number) - The pagination number.
+ per_page: `20` (optional, number) - The number of taxa to return per request. Max 100.
+ order: `+rank` (optional,string) - Sort an attribute either by descending (-) or ascending (+). Accepts a comma separated list for several attributes.
+ Response 200 (application/json)
+ Attributes
- data (array[Media])
## Create Taxon Media [/taxa/{id}/media]
### POST
+ Parameters
+ id (enum[string])
ID or Slug
- `n8rxo9rm` - The unique ID
- `lecythis-corrugata-rosea` - The unique slug
+ Request (multipart/form-data; boundary=---BOUNDARY)
-----BOUNDARY
Content-Disposition: form-data; name="image[file]"; filename="image.jpg"
Content-Type: image/jpeg
Content-Transfer-Encoding: base64
/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a
HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIy
MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIA
AhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAf/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEB
AAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AD//Z
-----BOUNDARY
+ Request (application/json)
+ Attributes
+ type: `image` (required, string)
+ url: `http://placekitten.com/800x800` (required, string)
+ title (optional, string)
+ Response 201 (application/json)
+ message: `OK` (string)
+ Attributes
- data (array[Media])
## Media Resource [/media/{id}]
### GET
+ Parameters
+ id: `n8rxo9rm` (string) - The unique ID
+ Response 200 (application/json)
+ Attributes
- data (Media)
# Group Aliases
Taxon's may be, and usually are, known by several different names. While the name used in the taxon's attributes is the official accepted name, the aliases associated can be of several types. Common names and synonyms are the most prevalent.
## Aliases Collection [/taxa/{id}/aliases{?page,per_page,order}]
### GET
+ Parameters
+ id (enum[string])
ID or Slug
- `n8rxo9rm` - The unique ID
- `lecythis-corrugata-rosea` - The unique slug
+ page: `1` (optional, number) - The pagination number.
+ per_page: `20` (optional, number) - The number of aliases to return per request. Max 100.
+ order: `type` (optional,string) - Sort an attribute either by descending (-) or ascending.
+ Response 200 (application/json)
+ Attributes
- data (array[Alias])
## Create Alias [/taxa/{id}/aliases]
### POST
+ Parameters
+ id (enum[string])
ID or Slug
- `n8rxo9rm` - The unique ID
- `lecythis-corrugata-rosea` - The unique slug
+ Request
+ Attributes
- name (required, string)
+ Response 200 (application/json)
+ Attributes
- data (Alias)
# Data Structures
## Basic Resource (object)
- id: `n8rxo9rm` (required,string) - The resource ID.
## Property (object)
- Include Basic Resource
- type: `property` (required,string)
- attributes
- Include Basic Property
## Full Property (object)
- Include Basic Resource
- type: `property` (required,string)
- attributes
- taxon_id (string) - The taxon that owns this property.
- Include Basic Property
- possible_values (array) - An array of the possible values. Arbitrary if `null`
- source (Source) - The source of this information.
## Media (object)
- Include Basic Resource
- type: `media` (required,string)
- attributes
- taxon_id (string)
- Include Basic Media
## Taxon (object)
- Include Basic Resource
- type: `taxon` (required, string)
- attributes
- Include Basic Taxon
## Basic Media (object)
- type: `image` (enum[string])
- image
- video
- url: `http://oakparks.com/images/taxon/aloe-vera.jpg` (string)
- thumbnail: `https://farm1.staticflickr.com/756/23567906910_71716056f9_q.jpg` (string)
- title: `Aloe Vera` (string)
- meta (optional, object)
- width: 2048 (number)
- height: 1200 (number)
## Basic Property (object)
- element: `space` (Elements) - The property element.
- type: `spacing` (required, string) - The property's type.
- value (required, array) - A list of values.
- description (optional, string) - The property's description.
## Basic Taxon (object)
- slug: `lecythis-corrugata-rosea` (string, required) - Slugified combination of binomial name and specific name.
- specific_name: `rosea` (string, required) - Specific name of the plant.
- binomial_name: `Lecythis corrugata` (string) - Binomial name of the plant.
- full_name: `Lecythis corrugata var. rosea` (string) - Fully qualilified scientific name.
- infraspecific: `false` (boolean) - Whether this taxon is infraspecific.
- rank (Ranks)
- image: `https://s3.us-east-2.amazonaws.com/oakparks.org/images/oakparks-image-not-found.jpg` (string) - Taxon image URL. ta
## Full Taxon (object)
- Include Basic Taxon
- tags (array[Tag])
- aliases (array[Alias]) - The taxon's aliases. Limit of 5. The full list can be retrieved as a [subresource](http://docs.oakparks.apiary.io/#reference/aliases/aliases-collection/get).
- parent (Taxon) - The parent taxon.
- children_count: 200 (number) - The number of child taxa.
## Pagination (object)
- total: `595029` (string)
- count: `20` (string)
- per_page: `20` (string)
- current_page: `1` (string)
- total_pages: `29752` (string)
## Links (object)
- self: `https://api.oakparks.com/v1/taxa?page=1` (string)
- first: `https://api.oakparks.com/v1/taxa?page=1` (string)
- next: `https://api.oakparks.com/v1/taxa?page=2` (string)
- last: `https://api.oakparks.com/v1/taxa?page=29752` (string)
## Resources (enum[string])
- taxon
- media
- property
## Ranks (enum[string])
- domain
- kingdom
- subkingdom
- subdivision
- subclass
- class
- order
- suborder
- family
- subfamily
- tribe
- subtribe
- genus
- subgenus
- section
- subsection
- series
- subseries
- species
- subspecies
- variety
- subvariety
- form
- subform
- superfamily
- cultivar
## Elements (enum[string])
- name
- appearance
- space
- uses
- wildlife
- sun
- water
- soil
- time
- reproduction
- habitat
- care
- hazard
- meta
## Alias (object)
- name
- type (enum[string])
- common
- synonym
- ambiguous synonym
- misapplied name
- duplicate
- author
## Tag (object)
- id: `3` (string) - ID of the tag.
- name: `perennials` (string) - The tag name.
## Type (object)
- Include Basic Resource
- type: `type` (required, string)
- attributes
- Include Basic Type
## Basic Type (object)
- element: `appearance` (string) - The element name.
- name: `Bloom color` (string) - The property type name.
- description (string) - Description of the property type.
- possible_values (array) - An array of possible values for this type. If empty, there is no constraint and can be arbitrary text.
- taxa_count: `345` (number) - The number of taxa that have this type of property assigned.
## Source (object)
- id (number)
- url (string)