The Plant Dictionary
PLANTZ API

The plantz.org API is a RESTful service that provides very basic search functionality and XML output for various types of plants. It's very much in beta and is really only intended for one of our own applications. It'll be made more scalable/reliable in the near future. At this stage, only XML data is available.

This Website is under Construction

Please keep in mind that this website is in a stage of very early development. As such, only limited data is made available.

Rate Limiting

Because the API is free and doesn't require registration, we've mitaged the potential for abuse by rate limiting unreasonable requests and we truncate various types of output.

Need Something More?

If you feel that our limits don't meet the needs of your service, get in touch and we'll white-list your application.

API Usage

Searching a Plant Name

http://www.plantz.org/api/<search term>/<page number>/<results limit>/api.xml 

Result:

Example

The ID returned in the XML relates to additional features that'll be available in the first release of the site.

We return plant common name, scientific name, scientific symbol and family. Additional fields (in fact, over 80 options) will become available in the live release.

The XML is structured in a basic manner. Total pages available (based on the limit of pages returned), the total number of results (matching your search term), the page limit (up to a maxium of 30) and the current page are all returned for easy pagination.

Error Codes

200OK
404No results found
421Invalid Request
422Invalid Request (Page Number)
422Invalid Request (Page Item Limit)
424Invalid Request (Page Results Limit)
406Min Length 3
420Rate Limited (Block active for Rule: X - unlock in -XX Sec.)


Example XML Error:

Example

Rate Limiting Rules (General)

▶ 5 requests in 5 seconds results in a 15 second block time.
▶ 10 requests in 30 seconds results in a 20 second block time.
▶ 100 requests in 3600 seconds results in a 600 second block time.
100 requests in a single hour is a general limit. We will increase this after the load to the server is known.
▶ 5 requests in 1 seconds results in a 86400 second block time.
10 requests in a single second results in a 10-minute block.
▶ 35 requests in 3 seconds results in a 259200 second block time.
25 requests in three seconds results in a three-day block. These limits WILL increase and are removed for white-listed clients.


Terms of Use

By using the Plantz.org API, you agree to these simple terms of use. You may use the API as-is for any purpose. You alone are responsible for any damage that you or your users encounter from using services from this API. The data provided may be cached locally for performance, but for no longer than 7 days. We accept no responsibility for any downtime, damage or errors, invalid/incorrect data or the consequences of information we provide. These terms are subject to change without notice and will be updated on this page.