# PlantCentral

> PlantCentral is a multilingual online marketplace for all kinds of plants, indoor and outdoor, with aquarium and aquatic plants as its speciality. Private and commercial sellers list plants; buyers send purchase inquiries to the seller through the site. Prices are in EUR.

Everything below is public and read-only; no API key is needed. Rate limit: 5 requests per second per IP (bursts up to 10), at most 2 at a time; beyond that you get HTTP 429, so slow down and retry. Responses are cacheable for an hour and carry an ETag: send it back as If-None-Match and an unchanged answer costs a 304 and no data.

## Offers API

- [Offers](https://plant-central.de/api/offers): every plant currently on sale, as schema.org JSON-LD (an ItemList of Product nodes with Offer, price, availability, shipping and seller). Paged: follow `next` until it is null.
- One offer: `https://plant-central.de/api/offers/{id}` (also under a language prefix), a single Product; the id is the number in its sku `PC-{id}`. List items already carry the same detail, so there is no need to fetch each offer.
- Cheaper answers: `format=md` (or the header `Accept: text/markdown`) returns a Markdown table, about a tenth of the JSON; `view=compact` keeps JSON but drops shipping, seller, rating and synonyms. Both are the best choice for scanning lists; fetch `https://plant-central.de/api/offers/{id}?format=md` for one offer's shipping and seller.
- [OpenAPI description](https://plant-central.de/api/openapi.json): machine-readable spec of both endpoints.
- [API catalog](https://plant-central.de/.well-known/api-catalog): the same entry points as an RFC 9727 linkset.
- [Agent Skill](https://plant-central.de/.well-known/agent-skills/index.json): these instructions packaged as an installable skill (Agent Skills Discovery v0.2.0).

Query parameters for the list:

- `q`: Plant name. Every word must match the scientific name or the variety, or the whole term a common or trade name in any site language, e.g. "anubias barteri" or "java fern". At most 8 words.
- `genus`: Exact genus name, e.g. "Anubias". Several values comma-separated, any of them matches.
- `family`: Exact family name, e.g. "Araceae". Several values comma-separated, any of them matches.
- `category`: Plant category: 1 = Aquarium, 2 = Terrarium, 3 = Houseplants, 8 = Carnivorous. Several values comma-separated, any of them matches. One of: `1`, `2`, `3`, `8`.
- `color`: Main color of the plant on offer, as given by the seller. Several values comma-separated, any of them matches. One of: `red`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `white`, `black`, `multicolor`, `mottled`, `halfmoon`.
- `position`: Where the plant goes in an aquarium or terrarium layout. Set per species, and not for every species: a plant without one is not returned. Several values comma-separated, any of them matches. One of: `foreground`, `midground`, `background`, `versatile`, `epiphyte`.
- `type`: What is sold. Several values comma-separated, any of them matches. One of: `basal`, `node`, `plant`, `seed`, `seedling`, `tc`.
- `minPrice`: Lowest price in EUR, inclusive.
- `maxPrice`: Highest price in EUR, inclusive.
- `availability`: Stock state. Without it the list has both. One of: `available`, `out-of-stock`.
- `seller`: Seller username.
- `modifiedSince`: Only offers changed at or after this time (ISO 8601). Without a UTC offset it is German time (Europe/Berlin). For incremental syncs.
- `sort`: Order of the list: by ID (stable, the default), price of the whole purchase ascending or descending, price per piece (unitPrice: per seed, cutting, plant) ascending or descending, or newest first. One of: `id`, `price`, `-price`, `newest`, `unitPrice`, `-unitPrice`.
- `view`: full (default): every detail incl. shipping, seller, rating, synonyms. compact: price, per-piece price, stock and the filterable facts only - faster and a fraction of the size; fetch one offer for its shipping. One of: `full`, `compact`.
- `format`: json (default, schema.org JSON-LD) or md: a Markdown table, the cheapest to read for a language model. Sending Accept: text/markdown does the same. One of: `json`, `md`.
- `page`: Page number, 1-based.
- `limit`: Offers per page.

## Reading the results

- Each offer is one listing of one seller. Several offers can have the same `name`; the `sku` is unique.
- The list contains in-stock and out-of-stock offers unless `availability` is set; the stock state is in `offers.availability`.
- `offers.price` is a decimal string in EUR (e.g. `"12.50"`) for the whole purchase, which can be several pieces: `unitAmount` says how many, `unitPrice` is the price per seed, cutting or plant (with a localised "2.50 € per seed" as description). Compare offers by `unitPrice` and quote it when `unitAmount` is above 1. During a price drop, `offers.priceSpecification` holds the previous price.
- Shipping: find the destination country (ISO code) in `offers.shippingDetails[].shippingDestination.addressCountry`; that entry's `shippingRate` is the cost. Shipping, return policy and rating are only present when the seller has set them.
- `alternateName` lists synonyms and the common and trade names of the plant, which is why a search for a common name can match an offer whose scientific name looks different.
- `description` is the seller's own text, in the language the seller wrote it in. URLs and labels (plant type, color) follow the language prefix.
- `additionalProperty`: `type`, `category`, `position` and `color` carry the value the filter of the same name takes, with the localised label as `description`, so you can search for more like an offer. Also `unitAmount` (pieces per purchase), `unitPrice` (per piece), `variety`, `variegation`, `dateModified`.
- `category` is a list: a plant is often in several categories (most aquarium plants are terrarium plants too), so read every value. Filtering by either category finds it.
- `color` is set by the seller per offer; `position` is set per species and not yet for every one.
- Dates without a UTC offset, e.g. `modifiedSince=2026-01-01`, are German time (Europe/Berlin).

## How to answer common questions

Category 1 (Aquarium) is aquarium plants.

- "Find the cheapest red stem plant": [`category=1&genus=Rotala,Ludwigia,Alternanthera,Ammannia,Hygrophila,Limnophila&color=red&sort=unitPrice&limit=10`](https://plant-central.de/api/offers?category=1&genus=Rotala,Ludwigia,Alternanthera,Ammannia,Hygrophila,Limnophila&color=red&sort=unitPrice&limit=10)
  `sort=unitPrice` ranks by price per stem; `sort=price` would rank a single stem above a cheaper bunch of ten.
  There is no growth-form field (stem, rosette, moss, carpeting or floating plant). Use your own plant knowledge to name the genera of that growth form and pass them comma-separated in `genus` (up to 20).
- "Find a red foreground plant for my aquarium": [`category=1&color=red&position=foreground&sort=price`](https://plant-central.de/api/offers?category=1&color=red&position=foreground&sort=price)
- "Find a green midground plant under 10 euros": [`category=1&color=green&position=midground&maxPrice=10&sort=price`](https://plant-central.de/api/offers?category=1&color=green&position=midground&maxPrice=10&sort=price)
- "List all white plants": [`color=white`](https://plant-central.de/api/offers?color=white)
- "Cheapest seeds, per seed": [`type=seed&sort=unitPrice&limit=10`](https://plant-central.de/api/offers?type=seed&sort=unitPrice&limit=10)
- "Which epiphytes can I tie to wood in my aquascape?": [`genus=Anubias,Bucephalandra,Microsorum,Leptochilus,Bolbitis,Taxiphyllum,Vesicularia&sort=price`](https://plant-central.de/api/offers?genus=Anubias,Bucephalandra,Microsorum,Leptochilus,Bolbitis,Taxiphyllum,Vesicularia&sort=price)
  Growth forms and layout roles are best searched by genus: `position` only knows the species that have one set, while a genus list from your own knowledge also finds the rest.
- "Is there a dwarf anubias, and what is shipping to Austria?": [`q=dwarf+anubias`](https://plant-central.de/api/offers?q=dwarf+anubias)
- "What is new on PlantCentral?": [`sort=newest&limit=10`](https://plant-central.de/api/offers?sort=newest&limit=10)

Rules that save requests and wrong answers:

- "Cheapest", "newest", "how many": one request with `sort` and a small `limit`; `numberOfItems` is the total count. A list item already has every detail, so do not fetch offers one by one.
- Scanning or comparing many offers: add `format=md` (or `view=compact`); only fetch the full offer when the user asks about shipping, the seller or the description.
- No results is a valid answer: tell the user, then relax one filter at a time, `position` first (not every species has one yet), then `color`. After dropping `position`, use your plant knowledge to say which of the results suit that position. Do not repeat a request you already made.
- `color` is what the seller chose, so it can surprise (a variety named "Gold / White" counts as white). Say so when an item looks odd rather than leaving it out silently.
- If two different filter values return the same offers, check the list values (`category`) before concluding that a filter does nothing: a plant can match both.
- Read these instructions once, in full. Link the user to the offer `url`, not to the API.

## Languages

German is the default and has no URL prefix. Prefix the path with the language code for localised URLs and labels in the API, the sitemaps and the pages:

- Deutsch (de_DE): [offers](https://plant-central.de/api/offers), [sitemap](https://plant-central.de/sitemap.xml)
- Nederlands (nl_NL): [offers](https://plant-central.de/nl/api/offers), [sitemap](https://plant-central.de/nl/sitemap.xml)
- English (en_US): [offers](https://plant-central.de/en/api/offers), [sitemap](https://plant-central.de/en/sitemap.xml)
- Français (fr_FR): [offers](https://plant-central.de/fr/api/offers), [sitemap](https://plant-central.de/fr/sitemap.xml)
- Italiano (it_IT): [offers](https://plant-central.de/it/api/offers), [sitemap](https://plant-central.de/it/sitemap.xml)
- Polski (pl_PL): [offers](https://plant-central.de/pl/api/offers), [sitemap](https://plant-central.de/pl/sitemap.xml)
- Español (es_ES): [offers](https://plant-central.de/es/api/offers), [sitemap](https://plant-central.de/es/sitemap.xml)
- Czech (cs_CZ): [offers](https://plant-central.de/cs/api/offers), [sitemap](https://plant-central.de/cs/sitemap.xml)
- Română (ro_RO): [offers](https://plant-central.de/ro/api/offers), [sitemap](https://plant-central.de/ro/sitemap.xml)

## Pages

- [Home](https://plant-central.de)
- Content pages are also available as Markdown: send `Accept: text/markdown` with the request to the normal page URL.
- Offer pages embed the same schema.org Product JSON-LD the API returns.