> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wiseyield.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Get regional prices

> Anonymized regional crop prices aggregated from user reports and sales.

```
GET https://www.wiseyield.co/api/v1/market/regional-prices
```

Returns aggregated, anonymized regional crop pricing combining two sources:

* **User-reported local prices** — what farms in the region say they're paying or selling for.
* **Recorded crop sales** — actual sale transactions on the platform.

Per-crop rows are returned only when the combined sample size is at least **5 distinct farms**, to preserve contributor privacy. Crops below the threshold are silently filtered out.

### Authentication

Requires a key with the `market:read` scope. See [Authentication](/authentication).

### Query parameters

<ParamField query="country" type="string" required>
  Country to aggregate over. Match the format used in the dashboard (e.g. `Egypt`, `Spain`, `Morocco`).
</ParamField>

<ParamField query="cropName" type="string">
  Optional. Filter to a single crop name (matches both `userLocalPrices.cropName` and `crops.cropType`).
</ParamField>

### Response

<ResponseField name="data" type="array">
  Per-crop aggregated price rows that meet the privacy threshold.

  <Expandable title="Row">
    <ResponseField name="cropName" type="string">Canonical crop name.</ResponseField>
    <ResponseField name="region" type="string">Echo of the `country` query parameter.</ResponseField>
    <ResponseField name="avgPrice" type="number">Volume-weighted average price across sources.</ResponseField>
    <ResponseField name="minPrice" type="number">Minimum observed price.</ResponseField>
    <ResponseField name="maxPrice" type="number">Maximum observed price.</ResponseField>
    <ResponseField name="currency" type="string">ISO 4217 currency derived from the country.</ResponseField>
    <ResponseField name="unit" type="string">Always `per_ton` in v1.</ResponseField>
    <ResponseField name="sampleSize" type="integer">Total distinct contributing farms.</ResponseField>

    <ResponseField name="sources" type="object">
      <Expandable title="Source breakdown">
        <ResponseField name="userReported" type="integer">Distinct farms contributing user-reported prices.</ResponseField>
        <ResponseField name="sales" type="integer">Distinct farms contributing recorded sales.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="Meta">
    <ResponseField name="country" type="string">Echo of the request.</ResponseField>
    <ResponseField name="currency" type="string">Currency the prices are expressed in.</ResponseField>
    <ResponseField name="minSampleSize" type="integer">Privacy threshold applied (currently `5`).</ResponseField>
    <ResponseField name="count" type="integer">Number of rows returned after filtering.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl 'https://www.wiseyield.co/api/v1/market/regional-prices?country=Egypt' \
    -H "Authorization: Bearer $WISEYIELD_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ country: 'Egypt' });
  const res = await fetch(
    `https://www.wiseyield.co/api/v1/market/regional-prices?${params}`,
    { headers: { Authorization: `Bearer ${process.env.WISEYIELD_API_KEY}` } }
  );
  const { data: prices, meta } = await res.json();
  console.log(`${meta.count} crops in ${meta.country} (${meta.currency})`);
  ```

  ```python Python theme={null}
  import os, requests
  res = requests.get(
      'https://www.wiseyield.co/api/v1/market/regional-prices',
      headers={'Authorization': f"Bearer {os.environ['WISEYIELD_API_KEY']}"},
      params={'country': 'Egypt'},
  )
  body = res.json()
  prices = body['data']
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "cropName": "Wheat",
        "region": "Egypt",
        "avgPrice": 287.43,
        "minPrice": 210.00,
        "maxPrice": 340.00,
        "currency": "EGP",
        "unit": "per_ton",
        "sampleSize": 18,
        "sources": { "userReported": 12, "sales": 6 }
      }
    ],
    "meta": {
      "country": "Egypt",
      "currency": "EGP",
      "minSampleSize": 5,
      "count": 1
    }
  }
  ```
</ResponseExample>

## Errors

| Status                    | When                                            |
| ------------------------- | ----------------------------------------------- |
| `400 VALIDATION_ERROR`    | `country` query parameter is missing            |
| `401`                     | Missing, malformed, expired, or revoked API key |
| `403 INSUFFICIENT_SCOPE`  | Key lacks `market:read` scope                   |
| `429 RATE_LIMIT_EXCEEDED` | Per-user rate limit reached                     |
| `5xx`                     | Server error                                    |

## Privacy

Rows are returned only when at least **5 distinct farms** contribute to a crop. This applies after merging user-reported and sales data — a crop with 3 user reports plus 2 sales rows clears the threshold, but a crop with only 4 of either does not. No individual farm identifier is ever exposed.