Open data API

Getting started

There is nothing to set up. Every endpoint is a plain GET.

curl https://milkweedusa.com/api/species.json

Or from a browser, from any origin:

const res = await fetch('https://milkweedusa.com/api/species.json');
const { species } = await res.json();

// Every milkweed native to Colorado, tallest first
const colorado = species
  .filter((s) => s.states.includes('CO') && s.nativeToUS)
  .sort((a, b) => b.heightInches[1] - a.heightInches[1]);

Start at /api/index.json, which lists every endpoint and the license terms in machine-readable form.

Rate limits, and why there are none

This is worth being straight about rather than inventing policy. The API is seven static files on Cloudflare's CDN. There is no database behind it, no application server, and no per-request cost that scales with you. Hammering it does not degrade anything for anybody else, so there is no quota, no key and no throttle.

Two things follow from that:

• Cache what you fetch. Every file is served with Cache-Control: public, max-age=3600. Respect it and you will be fetching once an hour rather than once a request, which is better for you as well.
• The data changes at the pace of a rebuild, which is measured in weeks. Polling it every minute achieves nothing.

If you are about to move serious volume, or you want to be told before a shape changes, say hello at contact@milkweedusa.com. Not because permission is needed, but because it is nice to know who is using it.

The endpoints

{
  "count": 72,
  "species": [{
    "slug": "swamp-milkweed",
    "scientificName": "Asclepias incarnata",
    "commonNames": ["Swamp Milkweed", "Rose Milkweed"],
    "nativeToUS": true,
    "heightInches": [36, 60],
    "bloomMonths": [6, 7, 8, 9],
    "states": ["AL", "AR", "..."],
    "references": { "powo": {...}, "gbif": {...} }
  }]
}

{
  "species": {
    "butterfly-weed": {
      "scientificName": "Asclepias tuberosa",
      "nativeCounties": ["01001", "01003", "..."],
      "introducedCounties": []
    }
  }
}

License and attribution

Everything is CC BY 4.0. Use it commercially, build a product on it, train a model on it. The one condition is credit:

Milkweed USA (https://milkweedusa.com), CC BY 4.0

A link back from wherever you use it is the form of credit that helps most.

Two things are not ours to license. Photographs carry their own licenses and are credited per image, so the API returns counts and filenames rather than rights. And the underlying government data, USDA PLANTS and NOAA, is public domain in its own right and you can go to the source directly.

Stability

• Fields get added, not removed. If a shape has to change in a breaking way it will go to a new path rather than mutating in place.
• Slugs are stable. A species slug is the primary key and is not going to change under you.
• There is no versioning yet, because nothing has needed it. If that changes it will be in the path.

Other machine-readable things

• /llms.txt and /llms-full.txt, the whole site as plain text for language models.
• Every page has a Markdown twin: add index.md to any path.
• /sitemap.xml includes the PDFs and the image manifest.
• Every page carries schema.org JSON-LD, including Dataset nodes on the climate and population pages.