API Endpoints

• plants.json
• symptoms.json
• animals.json
• taxa.json
• toxicity.json
• hotlines.json

Files & Models

• plants.json

  Our primary database. This includes a breakdown of all currently-supported plants along with their common names, symptoms, images and affected animal types.

  This is an array of objects with the following structure:

  type Symptom struct {
  	// The human-readable name of the symptom
  	Name string `json:"name"`
  
  	// A machine-friendly version of the name
  	Slug string `json:"slug"`
  }
  
  type Common struct {
  	// The human-readable name of the common name
  	Name string `json:"name"`
  
  	// A machine-friendly version of the common name
  	Slug string `json:"slug"`
  }
  
  type Image struct {
  	// The original remote source of the image
  	SourceUrl string `json:"source_url"`
  
  	// The original author of the image
  	Attribution string `json:"attribution"`
  
  	// The associated CC license
  	License string `json:"license"`
  
  	// The path to the image hosted on this site
  	RelativePath string `json:"relative_path"`
  }
  
  type Plant struct {
  	// The unique identifier of the plant
  	Pid string `json:"pid"`
  
  	// The human-friendly name of the plant
  	Name string `json:"name"`
  
  	// A list of any animals affected by the plant
  	Animals []string `json:"animals"`
  
  	// A list of common names ( see above )
  	Common []Common `json:"common"`
  
  	// A list of symptoms ( see above )
  	Symptoms []Symptom `json:"symptoms"`
  
  	// A list of images ( see above )
  	Images []Image `json:"images"`
  
  	// The wikipedia entry associated with the plant
  	WikipediaUrl string `json:"wikipedia_url"`
  
  	// The family classification of the plant
  	Family string `json:"family"`
  }

  Download

  $ curl -sL plantsm.art/api/plants.json > plants.json

• symptoms.json

  A distinct listing of all known symptoms with an associated listing of any related plant records.

  This is an array of objects with the following structure:

  type Symptom struct {
  	// The human-readable name of the symptom
  	Name string `json:"name"`
  
  	// A machine-friendly version of the name
  	Slug string `json:"slug"`
  
  	// The number of plants sharing this symptom
  	Count  int      `json:"count"`
  
  	// A list of ids for each associated plant
  	Plants []string `json:"plants"`
  }

  Download

  $ curl -sL plantsm.art/api/symptoms.json > symptoms.json

• animals.json

  A distinct listing of all supported animal types with an associated listing of any related plant records.

  This is an array of objects with the following structure:

  type Animal struct {
  	// The name of the animal
  	Name string `json:"name"`
  
  	// The number of plants affecting this animal
  	Count  int      `json:"count"`
  
  	// A list of ids for each affecting plant
  	Plants []string `json:"plants"`
  }

  Download

  $ curl -sL plantsm.art/api/animals.json > animals.json

  Supplemental

  Use these files if you wish to have animal-specific listings. The database holds dogs, cats and horses: the animals our sources vouch for.

  • cats.json
  • dogs.json
  • horses.json
• taxa.json

  Structured facts for each plant, collected from Wikidata, GBIF and the USDA PLANTS database. The object maps each plant id to one record. Every field is optional.

  This is an object of pid keys with the following structure:

  type Taxon struct {
  	// The Wikidata item id
  	Wikidata string `json:"wikidata"`
  
  	// The GBIF taxon key
  	Gbif string `json:"gbif"`
  
  	// The iNaturalist taxon id
  	Inat string `json:"inat"`
  
  	// The USDA PLANTS symbol
  	Usda string `json:"usda"`
  
  	// Extra English vernacular names from GBIF
  	Vernacular []string `json:"vernacular"`
  
  	// The USDA duration, for example Perennial
  	Duration []string `json:"duration"`
  
  	// The USDA growth habit, for example Vine
  	GrowthHabit []string `json:"growth_habit"`
  
  	// Areas where GBIF marks the plant as native
  	NativeTo []string `json:"native_to"`
  
  	// Countries with the most wild observations on GBIF
  	ObservedIn []string `json:"observed_in"`
  
  	// The same countries as ISO 3166 alpha-2 codes
  	ObservedCodes []string `json:"observed_codes"`
  
  	// Every country with ten or more GBIF observations,
  	// as ISO 3166 alpha-2 codes, most observed first
  	FoundCodes []string `json:"found_codes"`
  }

  Download

  $ curl -sL plantsm.art/api/taxa.json > taxa.json

• toxicity.json

  The toxicity section of the Wikipedia article for each plant that has one. The object maps each plant id to one record. The text is CC BY-SA 4.0, so give attribution when you republish it.

  This is an object of pid keys with the following structure:

  type Toxicity struct {
  	// The heading of the source section
  	Heading string `json:"heading"`
  
  	// The section text, paragraphs split by blank lines
  	Text string `json:"text"`
  
  	// The source Wikipedia article
  	Url string `json:"url"`
  }

  Download

  $ curl -sL plantsm.art/api/toxicity.json > toxicity.json

• hotlines.json

  Emergency telephone numbers for animal poisoning by country. This is the one file that does not come from plants.json. It is maintained by hand and validated by a build script. Every entry cites the operator page it came from and the date a person read it.

  Read the audience field before you show a number to anyone. Some services take calls from veterinarians only and an owner who rings one is turned away. Read checked too: services close and numbers change and a stale number is worse than no number.

  Coverage is not global. A country in the file with an empty services list has been checked and has no service an owner can call. A country that is absent has not been checked.

  This is an object with the following structure:

  type Hotlines struct {
  	// The most recent date on which a person checked an entry
  	Updated string `json:"updated"`
  
  	// What this file is, and what it does not cover
  	Notice string `json:"notice"`
  
  	// Countries by ISO 3166-1 alpha-2 code
  	Countries map[string]Country `json:"countries"`
  }
  
  type Country struct {
  	// The country name, in English
  	Name string `json:"name"`
  
  	// The date a person last read this country's sources
  	Checked string `json:"checked"`
  
  	// The services in this country. An empty list means we
  	// checked and found nothing an owner can call.
  	Services []Service `json:"services"`
  
  	// Why there is no service. Present when services is empty.
  	Note string `json:"note,omitempty"`
  
  	// The page the note comes from. Present when services is empty.
  	Source string `json:"source,omitempty"`
  }
  
  type Service struct {
  	// The organisation that answers the telephone
  	Org string `json:"org"`
  
  	// The number to dial, ready for a tel: link
  	Tel string `json:"tel"`
  
  	// The number as a reader should see it
  	Display string `json:"display"`
  
  	// Who may call: "owner" or "vet"
  	Audience string `json:"audience"`
  
  	// When the service answers
  	Hours string `json:"hours"`
  
  	// What a call costs, when the operator publishes it
  	Fee string `json:"fee,omitempty"`
  
  	// Anything a caller should know before dialling
  	Note string `json:"note,omitempty"`
  
  	// The operator page this entry came from
  	Source string `json:"source"`
  }

  Download

  $ curl -sL plantsm.art/api/hotlines.json > hotlines.json

Usage

These are known as "dumb" API endpoints. They are static flat files that are generated at "build time" before we deploy changes to production. They, like this site, live behind a CDN which is managed by Cloudflare. We do not impose rate-limits or any other restrictions with regards to access.

You may download these files locally without attribution and use them as you wish. The exception is toxicity.json: its text comes from Wikipedia under CC BY-SA 4.0, so keep the attribution when you republish it.

hotlines.json asks one thing of you instead. It holds emergency telephone numbers, and we check each one about once a year. If you put these numbers in front of people, show them the checked date, respect the audience field and tell your readers to call their own veterinarian first. A number that stopped working is worse than no number at all.

If you wish to use the associated images, be sure to abide by the associated Creative Commons license. You can find the specific license for each image using the .[].images[].license path in the plants.json dataset.