Catalog data
Catalog commands
Search, rank, and compare catalog coffees and suppliers, and find similar coffees.
Search the normalized green coffee catalog, rank candidates, compare suppliers, and find similar coffees from your terminal. For no-login browsing, use the web catalog at https://purveyors.io/catalog.
Access: Viewer. Any signed-in account.
purvey catalog search
Search coffees by origin, process, price, and catalog metadata.
Usage: purvey catalog search [options]
Access: Viewer. Any signed-in account.
- All filters are optional. Without flags, returns up to --limit results.
- Grading filters add a grading object to each coffee: disclosed screen size, labeled grade codes, lab analysis, and cup score with its protocol.
- Each coffee carries a taxonomy object with its standardized variety, species, and drying labels when the supplier text matched the vocabulary. An unknown code is an error; --variety and --drying-method still match by text.
- --ids fetches specific catalog items by ID, ignoring --limit and --offset.
- --offset + --limit enables pagination through large result sets.
- Without --include-proof, the output shape is unchanged.
- PURVEYORS_API_KEY or PARCHMENT_API_KEY overrides the scoped API key stored by
purvey auth login.
| Argument or flag | Details |
|---|---|
--origin <origin> | Only coffees from this origin; matches continent, country, or region names, case-insensitive and partial. |
--process <method> | Only coffees whose processing label contains this text, such as natural or washed (case-insensitive). |
--decaf <true|false> | true selects decaffeinated coffees; false excludes them. Omit for any coffee. |
--processing-base-method <method> | Only coffees whose structured base process exactly matches this value, such as Natural or Washed. List values with purvey catalog facets processing_base_method. |
--fermentation-type <type> | Only coffees whose structured fermentation type exactly matches this value, such as Anaerobic. List values with purvey catalog facets fermentation_type. |
--process-additive <additive> | Only coffees whose process discloses exactly this additive, such as hops. |
--processing-disclosure-level <level> | Only coffees whose supplier disclosed process details at exactly this level. |
--processing-confidence-min <n> | Only coffees whose process details were identified with at least this confidence. Range: 0 to 1. |
--price-min <n> | Lowest price per pound to include, in US dollars. |
--price-max <n> | Highest price per pound to include, in US dollars. |
--name <text> | Only coffees whose name contains this text (case-insensitive). |
--ids <n,n,...> | Fetch these catalog IDs, comma-separated, instead of searching; --limit and --offset are ignored. |
--variety <text> | Only coffees whose variety or cultivar contains this text (case-insensitive). |
--stocked-days <n> | Only coffees that came into stock within the last N days. |
--supplier <name> | Only coffees from suppliers whose name contains this text (case-insensitive). |
--drying-method <method> | Only coffees whose drying method or processing text contains this value, such as raised bed (case-insensitive). |
--flavor <keywords> | Comma-separated flavor keywords searched in coffee descriptions and tasting notes; a coffee matches if it mentions any of them. |
--stocked | Only coffees currently in stock; without it, results also include coffees no longer stocked. |
--sort <field> | Sort by price (cheapest first), price-desc, name, or origin (by country); without it, the most recently stocked coffees come first. |
--offset <n> | Number of results to skip when paging; must be a multiple of --limit. Default: 0. |
--limit <n> | Maximum number of coffees to return. Default: 10. Range: 1 to 1000. |
--include-proof | Add a proof summary to each coffee: how well its process, provenance, freshness, and pricing details are supported (strong, partial, limited, or not available). |
--elevation-min <masl> | Lowest growing elevation in meters; coffees whose disclosed range overlaps match. Range: 1 to 6000. |
--elevation-max <masl> | Highest growing elevation in meters. Range: 1 to 6000. |
--screen-min <n> | Smallest disclosed screen size (64ths of an inch); an 18+ lot matches any minimum up to its range. Range: 8 to 20. |
--screen-max <n> | Largest disclosed screen size (64ths of an inch). Range: 8 to 20. |
--grade <codes> | Comma-separated grade codes such as KE:AA,PREP:EP; a coffee matches if it carries any of them. List codes with purvey catalog grades. |
--grade-kind <kind> | Only coffees with a grade of this kind: size, altitude, defects, cup, or preparation. |
--peaberry | Only peaberry lots. |
--lab-analyzed | Only coffees with lab values such as moisture, water activity, density, or defect counts. |
--moisture-max <pct> | Highest disclosed moisture percentage; coffees without a moisture reading are excluded. Range: 0 to 20. |
--score-protocol <protocol> | Only cup scores from this protocol: sca_2004, cva_affective, q_arabica, coe, or supplier_unspecified. |
--variety-code <codes> | Comma-separated variety codes such as gesha,bourbon; a coffee matches if it carries any of them, and a family code also matches the codes under it (bourbon matches pink_bourbon). Find codes with purvey catalog taxonomies. |
--species-code <codes> | Comma-separated species codes such as arabica or canephora (Robusta); matches coffees whose supplier states the species. |
--drying-method-code <codes> | Comma-separated drying method codes such as raised_bed,patio; raised_bed also matches african_bed. |
Examples
purvey catalog search --decaf true --stocked --pretty
purvey catalog search --decaf false --process "natural" --pretty
purvey catalog search --origin "Ethiopia" --process "natural" --pretty
purvey catalog search --processing-base-method "Natural" --fermentation-type "Anaerobic" --pretty
purvey catalog search --process-additive "hops" --processing-confidence-min 0.8 --pretty
purvey catalog search --variety "gesha" --stocked --pretty
purvey catalog search --stocked-days 30 --pretty
purvey catalog search --supplier "Royal" --flavor "blueberry,jasmine" --stocked --pretty
purvey catalog search --origin "Ethiopia" --include-proof --json
purvey catalog search --grade KE:AA,KE:AB --screen-min 17 --stocked --pretty
purvey catalog search --grade-kind altitude --elevation-min 1600 --pretty
purvey catalog search --variety-code bourbon,gesha --stocked --prettypurvey catalog get
Get details for a specific coffee by ID.
Usage: purvey catalog get <id> [options]
Access: Viewer. Any signed-in account.
| Argument or flag | Details |
|---|---|
<id> | Required: Catalog ID of the coffee. |
--include-proof | Add the proof summary: how well the coffee's process, provenance, freshness, and pricing details are supported. |
Examples
purvey catalog get 128 --pretty
purvey catalog get 128 --include-proof --jsonpurvey catalog stats
Aggregate statistics for the catalog.
Usage: purvey catalog stats
Access: Viewer. Any signed-in account.
Examples
purvey catalog stats --prettypurvey catalog facets
List counted catalog facet values for filter discovery.
Usage: purvey catalog facets [field] [options]
Access: Viewer. Any signed-in account.
- Without a field, prints every facet except the grading and code facets, with its counted values and meta (values, facets, meta); name one of those fields to get its counts.
- Code facets (varieties, species_codes, drying_methods) roll up: a family counts every coffee carrying it or any code under it, once.
- With a field, prints { field, facet, data, meta }: that facet's counted values and meta.
- Counts for multi-valued dimensions can overlap, so do not sum them.
- Defaults to currently stocked coffees; use --all for every coffee you can see.
| Argument or flag | Details |
|---|---|
[field] | Optional: The facet to list: supplier, country, decaf, processing_base_method, fermentation_type, drying_method, wholesale, grade_size, grade_altitude, grade_defects, grade_cup, grade_preparation, screen_size_min, elevation_band, varieties, species_codes, or drying_methods. Without it, every facet except the grading and code facets is listed. |
--decaf <true|false> | Count only decaffeinated coffees (true) or coffees that are not decaffeinated (false). Omit for any coffee. |
--all | Count every coffee you can see, including ones no longer stocked; without it, only coffees currently in stock are counted. |
Examples
purvey catalog facets decaf --pretty
purvey catalog facets country --decaf true --pretty
purvey catalog facets supplier --pretty
purvey catalog facets country --all --json
purvey catalog facets --pretty
purvey catalog facets grade_altitude --pretty
purvey catalog facets varieties --prettypurvey catalog rank
Rank catalog coffees for a goal: premium, value, fresh arrivals, or rare origins.
Usage: purvey catalog rank [options]
Access: Viewer. Any signed-in account.
- Objectives are premium, value, fresh_arrival, and rare_origin.
- Uses the Purveyor Score as the quality signal.
- Output metadata reports stocked_only/scope, sample scope, and truncation; rare_origin is rarity within sampled matching candidates.
| Argument or flag | Details |
|---|---|
--objective <objective> | What to rank for: premium (highest Purveyor Score), value (score per dollar), fresh_arrival (newest arrivals), or rare_origin (least common origins in the sample). Default: premium. |
--supplier <name> | Only coffees from suppliers whose name contains this text. |
--country <country> | Only coffees from this country. |
--process <method> | Only coffees with this processing method, such as washed or natural. |
--stocked | Only coffees currently in stock; this is already the default unless you pass --all. |
--all | Rank every coffee you can see, including ones no longer stocked, instead of only coffees in stock. |
--price-max <n> | Highest price per pound to include, in US dollars. |
--min-score <n> | Lowest Purveyor Score to include. |
--non-wholesale-only | Leave out wholesale listings, keeping retail and listings with unknown wholesale status, before sampling. |
--sample-size <n> | Number of matching coffees to consider before ranking; a smaller sample is faster but may miss candidates. Default: 5000. Range: 1 to 5000. |
--limit <n> | Maximum number of ranked coffees to return. Default: 10. Range: 1 to 50. |
Examples
purvey catalog rank --objective premium --stocked --pretty
purvey catalog rank --objective value --country Ethiopia --price-max 12 --json
purvey catalog rank --objective premium --supplier "Royal Coffee" --limit 5 --jsonpurvey catalog supplier-list
Summarize suppliers from the catalog coffees they list.
Usage: purvey catalog supplier-list [options]
Access: Viewer. Any signed-in account.
- Summarizes supplier counts, stocked counts, Purveyor Score coverage, average score, average confidence, price range, origin/process coverage, and representative top coffees with score qualifiers.
- Country and non-wholesale filters apply to coffees before suppliers are summarized.
- Output metadata reports source-ordered pagination, rows examined, and whether the aggregate is sample-limited.
| Argument or flag | Details |
|---|---|
--country <country> | Only count coffees from this country. |
--stocked | Only count coffees currently in stock; without it, coffees no longer stocked count too. |
--non-wholesale-only | Leave out wholesale listings before suppliers are summarized. |
--sample-size <n> | Number of catalog coffees to read per page before summarizing suppliers. Default: 5000. Range: 1 to 5000. |
--limit <n> | Maximum number of suppliers to return. Default: 25. Range: 1 to 100. |
Examples
purvey catalog supplier-list --country Ethiopia --non-wholesale-only --prettypurvey catalog supplier-detail
Show aggregate detail for a supplier query.
Usage: purvey catalog supplier-detail <supplier> [options]
Access: Viewer. Any signed-in account.
- Supplier matching is case-insensitive and partial, mirroring catalog search.
- Output metadata reports source-ordered pagination, rows examined, and whether the aggregate is sample-limited.
| Argument or flag | Details |
|---|---|
<supplier> | Required: Supplier name to look up (case-insensitive, partial match). |
--country <country> | Only count coffees from this country. |
--stocked | Only count coffees currently in stock; without it, coffees no longer stocked count too. |
--non-wholesale-only | Leave out wholesale listings before the supplier is summarized. |
--top-coffees <n> | Number of representative top coffees to include. Default: 5. Range: 1 to 25. |
--sample-size <n> | Number of catalog coffees to read per page before summarizing. Default: 5000. Range: 1 to 5000. |
Examples
purvey catalog supplier-detail "Royal Coffee" --prettypurvey catalog supplier-rank
Rank suppliers by average Purveyor Score and stocked coverage.
Usage: purvey catalog supplier-rank [options]
Access: Viewer. Any signed-in account.
- Ranks suppliers by average Purveyor Score, then currently stocked count.
- Country and non-wholesale filters apply to coffees before suppliers are ranked.
- Output metadata reports source-ordered pagination, rows examined, and whether the aggregate is sample-limited.
| Argument or flag | Details |
|---|---|
--country <country> | Only count coffees from this country. |
--stocked | Only count coffees currently in stock; without it, coffees no longer stocked count too. |
--non-wholesale-only | Leave out wholesale listings before suppliers are ranked. |
--min-coffees <n> | Minimum number of matching coffees a supplier needs to be ranked. Default: 1. Range: 1 to 100. |
--sample-size <n> | Number of catalog coffees to read per page before ranking suppliers. Default: 5000. Range: 1 to 5000. |
--limit <n> | Maximum number of suppliers to return. Default: 25. Range: 1 to 100. |
Examples
purvey catalog supplier-rank --country Ethiopia --non-wholesale-only --min-coffees 3 --prettypurvey catalog similar
Beta: find likely same-lot candidates and similar coffees for a catalog coffee.
Usage: purvey catalog similar <id> [options]
Access: Viewer. Any signed-in account.
- Needs a sign-in (
purvey auth login) or any API key with catalog:read. The free Green API plan includes it within its monthly quota. - Results are beta candidates to review, not confirmed matches.
- Default JSON output groups results under data.target, data.groups.canonical_candidates, data.groups.similar_recommendations, optional data.matches, and meta.
- canonical_candidates are likely same-lot candidates; similar_recommendations are profile substitutes and expose blocker reasons when identity details disagree.
- Keeps classification_version, query_strategy, proof summaries, pricing metadata, blocker details, and score dimensions as returned.
| Argument or flag | Details |
|---|---|
<id> | Required: Catalog ID of the coffee to match. |
--threshold <score> | Minimum similarity score a match needs; higher values return fewer, closer matches. Default: 0.7. Range: 0.5 to 0.99. |
--limit <count> | Maximum number of matches to return. Default: 10. Range: 1 to 25. |
--stocked-only | Only return coffees currently in stock; without it, matches can include coffees no longer stocked. |
--mode <mode> | Which matches to return: all, likely_same (probably the same lot listed elsewhere), or similar_profile (substitutes with a similar profile). Default: all. |
Examples
purvey catalog similar 1182 --threshold 0.85 --stocked-only --json
purvey catalog similar 1182 --mode likely_same --json | jq '.data.groups.canonical_candidates'purvey catalog compare
Compare 2 to 6 coffees side by side, priced at your quantity.
Usage: purvey catalog compare <ids> [options]
Access: Viewer. Any signed-in account.
- Rows are grouped Price, Availability, Origin, Process, Coffee, Grading, Taste, and Listing, each marked same, partial, or different.
- Price rows name the cheapest lots in bestLotIds; grading rows never carry best marks.
- Viewer accounts compare 2 coffees; member accounts and API keys compare up to 6.
| Argument or flag | Details |
|---|---|
<ids> | Required: 2 to 6 catalog IDs, space- or comma-separated. |
--quantity <lb> | Pounds you plan to buy, any positive number up to 10000; each coffee is priced at the tier that applies to this quantity. Default: 1. |
Examples
purvey catalog compare 416 8806 --pretty
purvey catalog compare 416 8806 1182 --quantity 5 --json | jq '.data.bestPriceLotIds'purvey catalog price-history
Daily smallest-tier price history for one coffee.
Usage: purvey catalog price-history <id> [options]
Access: Viewer. Any signed-in account.
- Prices track the smallest order tier.
- Parchment decides access: member accounts, Parchment Intelligence, and API keys with catalog:read, including the key
purvey auth loginstores. - Events flag days when the smallest tier's quantity changed, which makes prices before and after not directly comparable.
| Argument or flag | Details |
|---|---|
<id> | Required: Catalog ID of the coffee. |
--days <n> | How many days of history to return. Default: 180. Range: 7 to 365. |
Examples
purvey catalog price-history 1182 --pretty
purvey catalog price-history 1182 --days 90 --json | jq '.data.summary'purvey catalog grades
Explain green grade codes such as KE:AA, ET:G1, GT:SHB, or PREP:EP.
Usage: purvey catalog grades [codes] [options]
Access: Viewer. Any signed-in account.
- Codes are <system>:<token>; composite grades such as ET:G1 carry more than one kind.
- Implied ranges come from the published definition, not from any listing.
- Codes not in the vocabulary are listed under unknownCodes.
| Argument or flag | Details |
|---|---|
[codes] | Optional: optional grade codes to explain, space- or comma-separated. |
--kind <kind> | Only codes of this kind: size, altitude, defects, cup, or preparation. |
--system <system> | Only codes from this grading system, such as KE, ET, BR, ALT, or PREP. |
--include-retired | Include retired codes, which stay valid on older listings. |
Examples
purvey catalog grades KE:AA ET:G1 --pretty
purvey catalog grades --kind altitude --json | jq '.data[].code'purvey catalog taxonomies
Look up variety, species, and drying method codes, such as gesha or raised_bed.
Usage: purvey catalog taxonomies [search] [options]
Access: Viewer. Any signed-in account.
- Each entry has a code, a label, its family (parent_code), and the supplier spellings that map to it.
- Use the codes with
purvey catalog search --variety-code,--species-code, and--drying-method-code. - An empty result means the name is not in the vocabulary yet, not that no coffee has it.
| Argument or flag | Details |
|---|---|
[search] | Optional: optional name to find; matches a code, a label, or a supplier spelling (geisha finds gesha). |
--taxonomy <name> | Only this vocabulary: variety, species, or drying_method. |
--family <code> | Only this family code and the codes under it, such as bourbon. |
--include-retired | Include retired codes, which stay valid on older listings. |
Examples
purvey catalog taxonomies geisha --pretty
purvey catalog taxonomies --taxonomy variety --family bourbon --pretty