Prices API

Search, retrieve, and analyze agricultural commodity price data

Search Prices

POST/api/v1/prices/searchSecret Key

Search and filter price records with advanced criteria

Request Body

Parameters

product_uuidstring (UUID)

Filter by specific product

market_uuidstring (UUID)

Filter by specific market

county_idinteger

Filter by county ID

start_datestring (YYYY-MM-DD)

Start of date range

end_datestring (YYYY-MM-DD)

End of date range

min_pricenumber

Minimum price filter

max_pricenumber

Maximum price filter

pageintegerdefault: 1

Page number for pagination

page_sizeintegerdefault: 20

Items per page (max: 100)

Example Request

Search for maize prices in Nairobi County during January 2024

Request

curl -X POST "https://api.shambarecords.com/api/v1/prices/search" \
  -H "X-API-Key: sr_sec_your_secret_key" \
  -H "X-Signature: generated_signature" \
  -H "X-Signature-Timestamp: 1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "product_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "county_id": 47,
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "page": 1,
    "page_size": 20
  }'

Response

{
  "data": [
    {
      "uuid": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
      "product": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Maize",
        "category": "Cereals"
      },
      "market": {
        "uuid": "b2c3d4e5-f6a7-4890-b123-456789abcdef",
        "name": "Gikomba Market",
        "type": "Wholesale"
      },
      "county": {
        "id": 47,
        "name": "Nairobi"
      },
      "price": 4500.00,
      "unit": "90kg bag",
      "currency": "KES",
      "recorded_at": "2024-01-15T10:30:00Z",
      "source": "Market Survey",
      "quality_grade": "Grade 1"
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 20,
    "total": 45,
    "total_pages": 3
  }
}

Get Price by UUID

GET/api/v1/prices/:uuidPublic Key

Retrieve a specific price record by its UUID

Path Parameters

Parameters

uuidstring (UUID)required

The unique identifier of the price record

Example Request

Request

curl -X GET "https://api.shambarecords.com/api/v1/prices/a1b2c3d4-e5f6-4789-a012-3456789abcde" \
  -H "X-API-Key: sr_pub_your_public_key"

Response

{
  "data": {
    "uuid": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
    "product": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Maize",
      "category": "Cereals",
      "description": "White maize grain"
    },
    "market": {
      "uuid": "b2c3d4e5-f6a7-4890-b123-456789abcdef",
      "name": "Gikomba Market",
      "type": "Wholesale",
      "county": "Nairobi",
      "sub_county": "Starehe"
    },
    "price": 4500.00,
    "unit": "90kg bag",
    "currency": "KES",
    "recorded_at": "2024-01-15T10:30:00Z",
    "source": "Market Survey",
    "quality_grade": "Grade 1",
    "notes": "Good quality white maize",
    "created_at": "2024-01-15T11:00:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}

Get Latest Prices

POST/api/v1/prices/latestPublic Key

Get the most recent prices for products, optionally filtered by location

Request Body

Parameters

product_uuidsarray of UUIDs

List of product UUIDs to fetch (optional, returns all if omitted)

market_uuidstring (UUID)

Filter by specific market

county_idinteger

Filter by county ID

limitintegerdefault: 10

Maximum number of results per product

Example Request

Get latest prices for selected products in Kiambu County

Request

curl -X POST "https://api.shambarecords.com/api/v1/prices/latest" \
  -H "X-API-Key: sr_pub_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_uuids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "661f9511-f39c-52e5-b827-557766551111"
    ],
    "county_id": 22,
    "limit": 5
  }'

Response

{
  "data": [
    {
      "product": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Maize"
      },
      "prices": [
        {
          "uuid": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
          "market": {
            "uuid": "b2c3d4e5-f6a7-4890-b123-456789abcdef",
            "name": "Kiambu Town Market"
          },
          "price": 4200.00,
          "unit": "90kg bag",
          "recorded_at": "2024-02-05T09:00:00Z"
        }
      ]
    },
    {
      "product": {
        "uuid": "661f9511-f39c-52e5-b827-557766551111",
        "name": "Beans"
      },
      "prices": [
        {
          "uuid": "c3d4e5f6-a7b8-4901-c234-56789abcdef0",
          "market": {
            "uuid": "d4e5f6a7-b8c9-4012-d345-6789abcdef01",
            "name": "Kikuyu Market"
          },
          "price": 12000.00,
          "unit": "90kg bag",
          "recorded_at": "2024-02-05T10:30:00Z"
        }
      ]
    }
  ]
}

Get Price Statistics

POST/api/v1/prices/statisticsSecret Key

Calculate statistical aggregates (average, min, max) for price data

Request Body

Parameters

product_uuidstring (UUID)required

Product to calculate statistics for

market_uuidstring (UUID)

Filter by specific market

county_idinteger

Filter by county ID

start_datestring (YYYY-MM-DD)required

Start of date range

end_datestring (YYYY-MM-DD)required

End of date range

group_bystringdefault: month

Group results by: 'day', 'week', 'month', 'market', 'county'

Example Request

Calculate monthly price statistics for maize in 2024

Request

curl -X POST "https://api.shambarecords.com/api/v1/prices/statistics" \
  -H "X-API-Key: sr_sec_your_secret_key" \
  -H "X-Signature: generated_signature" \
  -H "X-Signature-Timestamp: 1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "product_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "group_by": "month"
  }'

Response

{
  "data": {
    "product": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Maize",
      "unit": "90kg bag"
    },
    "period": {
      "start_date": "2024-01-01",
      "end_date": "2024-12-31"
    },
    "statistics": [
      {
        "period": "2024-01",
        "average_price": 4350.00,
        "min_price": 3800.00,
        "max_price": 4900.00,
        "median_price": 4400.00,
        "sample_count": 145,
        "std_deviation": 285.50
      },
      {
        "period": "2024-02",
        "average_price": 4280.00,
        "min_price": 3900.00,
        "max_price": 4700.00,
        "median_price": 4300.00,
        "sample_count": 132,
        "std_deviation": 245.30
      }
    ],
    "overall": {
      "average_price": 4315.00,
      "min_price": 3800.00,
      "max_price": 4900.00,
      "total_samples": 277
    }
  }
}

Price Object Schema

Response Schema

uuidstring (UUID)

Unique identifier for the price record

productobject

Product information (uuid, name, category)

marketobject

Market information (uuid, name, type, location)

countyobjectnullable

County information (id, name)

pricenumber

Price value in the specified currency

unitstring

Unit of measurement (e.g., '90kg bag', '1kg', 'piece')

currencystring

Currency code (KES for Kenyan Shillings)

recorded_atstring (ISO 8601)

Timestamp when the price was recorded

sourcestring

Source of the price data

quality_gradestringnullable

Quality grade of the product

notesstringnullable

Additional notes about the price

created_atstring (ISO 8601)

Timestamp when the record was created

updated_atstring (ISO 8601)

Timestamp when the record was last updated