For the complete documentation index, see llms.txt. This page is also available as Markdown.

Beckn Payload Mappers

Beckn Payload Mapping Specification

In Beckn, these fields should not go into the context. They belong in the intent section of the search request, typically under message.intent.fulfillment.stops[0].location for location filters and message.intent.tags (or item descriptors depending on your domain schema) for custom search filters.

Agrovet Provider API

  1. Endpoint GET /service-points

API Field

Type

Beckn Field

Notes

county_code

string

message.intent.fulfillment.end.location.area_code

County filter (KE-001 format). Validation regex ^KE-[0-9]{3}$ should happen at API layer

crop

CropCode

message.intent.tags[].descriptor.code = crop

Matches items where item contains this crop in crop_codes

category

string

message.intent.item.category.descriptor.code

Item category: fertiliser, seed, pesticide, fungicide, herbicide, veterinary, equipment

growth_stage

GrowthStageCode

message.intent.tags[].descriptor.code = growth_stage

Matches item growth stages

item_query

string

message.intent.item.descriptor.name

Case-insensitive item name search

in_stock_only

boolean

message.intent.tags[].descriptor.code = in_stock_only

Default value true

type

string

message.intent.provider.category_id

Service point type: agrovet, aggregation_centre, extension_office, vet_clinic

lat

number

message.intent.fulfillment.end.location.gps

Must combine with longitude

lon

number

message.intent.fulfillment.end.location.gps

Format: "lat,lon"

radius_km

number

message.intent.fulfillment.end.location.circle.radius.value

Valid only with lat + lon

limit

integer

message.intent.tags[].descriptor.code = limit

Pagination extension

offset

integer

message.intent.tags[].descriptor.code = offset

Pagination extension

Endpoint : GET /items

API Field

Type

Exact Beckn Field

Remarks

crop

CropCode

message.intent.item.tags[].descriptor.code = crop

Matches if returned item has this crop in item.tags (crop_codes)

category

string

message.intent.item.category.descriptor.code

Item category filter

growth_stage

GrowthStageCode

message.intent.item.tags[].descriptor.code = growth_stage

Matches item growth stage metadata

item_query

string

message.intent.item.descriptor.name

Case-insensitive substring search on item name

item_query (active ingredient)

string

message.intent.item.tags[].descriptor.code = active_ingredient

Search extension for agricultural metadata

in_stock_only

boolean

message.intent.item.tags[].descriptor.code = in_stock_only

Default true; filters available inventory

max_price_kes

number

message.intent.item.price.maximum_value (domain extension)

Inclusive upper price filter; recommended as tag if schema does not support price constraint

limit

integer

message.intent.tags[].descriptor.code = limit

Page size. Default: 20. Maximum: 100. Domain extension

offset

integer

message.intent.tags[].descriptor.code = offset

Records to skip. Default: 0. Must be >= 0. Domain extension

Example Payload:

{

"context": {

"domain": "agri:input-marketplace",

"action": "search",

"version": "1.1.0",

"bap_id": "bap.example.org",

"transaction_id": "tx-123456789",

"message_id": "msg-123456789",

"timestamp": "2026-08-03T12:00:00Z",

"ttl": "PT30S"

},

"message": {

"intent": {

"item": {

"descriptor": {

"name": "Roundup"

},

"category": {

"descriptor": {

"code": "HERBICIDE"

}

},

"tags": [

{

"descriptor": {

"code": "crop"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "MAIZE"

}

]

},

{

"descriptor": {

"code": "growth_stage"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "VEGETATIVE"

}

]

},

{

"descriptor": {

"code": "active_ingredient"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "Glyphosate"

}

]

},

{

"descriptor": {

"code": "in_stock_only"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "true"

}

]

},

{

"descriptor": {

"code": "max_price_kes"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "2500"

}

]

}

]

},

"tags": [

{

"descriptor": {

"code": "limit"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "20"

}

]

},

{

"descriptor": {

"code": "offset"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "0"

}

]

}

]

}

}

}

Response Objects

ServicePoint

API Field

Type

Exact Beckn Field

Remarks

id

string

message.catalog.providers[].id

Stable provider identifier (KE-SP-####)

type

string

message.catalog.providers[].categories[].descriptor.code

Service point type (agrovet, aggregation_centre, extension_office, vet_clinic)

name

string

message.catalog.providers[].descriptor.name

Business/service point name

county_code

string

message.catalog.providers[].locations[].address.area_code

CountyCode (KE-001 format)

county_name

string

message.catalog.providers[].locations[].address.state

Denormalised county name

sub_county

string

message.catalog.providers[].locations[].address.city

Constituency mapping

ward

string

message.catalog.providers[].locations[].address.locality

Ward mapping

geo.lat

number

message.catalog.providers[].locations[].gps

GPS format "lat,long"

geo.lon

number

message.catalog.providers[].locations[].gps

GPS format "lat,long"

phone

string

message.catalog.providers[].contacts.phone

Business contact (not masked)

opening_hours

string

message.catalog.providers[].tags[].descriptor.code = opening_hours

Domain metadata

licence_number

string

message.catalog.providers[].tags[].descriptor.code = licence_number

Synthetic licence metadata

services

string[]

message.catalog.providers[].tags[].descriptor.code = services

Service capabilities

delivery_available

boolean

message.catalog.providers[].fulfillments[].tags[].descriptor.code = delivery_available

Delivery capability

delivery_radius_km

integer | null

message.catalog.providers[].fulfillments[].stops[].location.circle.radius.value

Delivery radius. Present only when delivery_available=true

items

object[]

message.catalog.providers[].items[] or message.catalog.items[]

Stocked items associated with provider

last_verified_on

string

message.catalog.providers[].tags[].descriptor.code = last_verified_on

YYYY-MM-DD verification metadata

distance_km

number | null

message.catalog.providers[].tags[].descriptor.code = distance_km

Calculated Haversine distance from query location

Example Reponse:

{

"context": {

"domain": "agri:input-marketplace",

"action": "on_search",

"version": "1.1.0",

"bap_id": "bap.example.org",

"bpp_id": "bpp.example.org",

"transaction_id": "tx-123456789",

"message_id": "msg-123456789",

"timestamp": "2026-08-03T12:00:01Z"

},

"message": {

"catalog": {

"descriptor": {

"name": "Agricultural Service Providers"

},

"providers": [

{

"id": "KE-SP-0205",

"descriptor": {

"name": "Lakeview Agrovet Ltd"

},

"categories": [

{

"id": "CAT-AGROVET",

"descriptor": {

"code": "agrovet",

"name": "Agrovet"

}

}

],

"locations": [

{

"id": "LOC-0205",

"gps": "-0.278,36.0362",

"address": {

"area_code": "KE-032",

"state": "Nakuru",

"city": "Kuresoi North",

"locality": "Kamara"

}

}

],

"contacts": {

"phone": "+254722213974"

},

"tags": [

{

"descriptor": {

"code": "opening_hours"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "Mon-Sat 07:30-18:00"

}

]

},

{

"descriptor": {

"code": "licence_number"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "AGV/032/2024/8185"

}

]

},

{

"descriptor": {

"code": "services"

},

"list": [

{

"descriptor": {

"code": "service"

},

"value": "training"

},

{

"descriptor": {

"code": "service"

},

"value": "veterinary_consultation"

},

{

"descriptor": {

"code": "service"

},

"value": "spraying_service"

}

]

},

{

"descriptor": {

"code": "last_verified_on"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "2026-06-15"

}

]

},

{

"descriptor": {

"code": "distance_km"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": ""

}

]

}

],

"fulfillments": [

{

"id": "FUL-DELIVERY",

"type": "Delivery",

"stops": [

{

"type": "end",

"location": {

"circle": {

"radius": {

"unit": "km",

"value": "10"

}

}

}

}

],

"tags": [

{

"descriptor": {

"code": "delivery_available"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "true"

}

]

}

]

}

],

"items": [

{

"id": "KE-SP-0205-IT-02",

"descriptor": {

"name": "CAN Fertiliser 50kg"

},

"category_ids": [

"CAT-FERTILISER"

],

"price": {

"currency": "KES",

"value": "2604.00"

},

"tags": [

{

"descriptor": {

"code": "crop_codes"

},

"list": [

{

"descriptor": {

"code": "crop"

},

"value": "maize"

},

{

"descriptor": {

"code": "crop"

},

"value": "beans"

},

{

"descriptor": {

"code": "crop"

},

"value": "wheat"

},

{

"descriptor": {

"code": "crop"

},

"value": "potato"

},

{

"descriptor": {

"code": "crop"

},

"value": "sorghum"

},

{

"descriptor": {

"code": "crop"

},

"value": "millet"

}

]

},

{

"descriptor": {

"code": "growth_stages"

},

"list": [

{

"descriptor": {

"code": "stage"

},

"value": "vegetative"

}

]

},

{

"descriptor": {

"code": "pack_size"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "50kg"

}

]

},

{

"descriptor": {

"code": "in_stock"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "true"

}

]

}

]

},

{

"id": "KE-SP-0205-IT-10",

"descriptor": {

"name": "Maize Fungicide 1L"

},

"category_ids": [

"CAT-FUNGICIDE"

],

"price": {

"currency": "KES",

"value": "1413.00"

},

"tags": [

{

"descriptor": {

"code": "crop_codes"

},

"list": [

{

"descriptor": {

"code": "crop"

},

"value": "maize"

},

{

"descriptor": {

"code": "crop"

},

"value": "wheat"

}

]

},

{

"descriptor": {

"code": "growth_stages"

},

"list": [

{

"descriptor": {

"code": "stage"

},

"value": "vegetative"

},

{

"descriptor": {

"code": "stage"

},

"value": "flowering"

}

]

},

{

"descriptor": {

"code": "pack_size"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "1L"

}

]

},

{

"descriptor": {

"code": "active_ingredient"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "mancozeb"

}

]

},

{

"descriptor": {

"code": "in_stock"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "true"

}

]

}

]

}

]

}

]

}

}

}

Item

API Field

Type

Exact Beckn Field

Remarks

item_id

string

message.catalog.items[].id

Stable item identifier ({service_point_id}-IT-{NN})

name

string

message.catalog.items[].descriptor.name

Product name

category

string

message.catalog.items[].category.descriptor.code

fertiliser, seed, pesticide, fungicide, herbicide, veterinary, equipment

crop_codes

CropCode[]

message.catalog.items[].tags[].descriptor.code = crop

Agriculture-specific metadata

growth_stages

GrowthStageCode[]

message.catalog.items[].tags[].descriptor.code = growth_stage

Agriculture-specific metadata

unit

InputUnitCode

message.catalog.items[].quantity.unitized.measure.unit

kg, g, l, ml, sachet, bag, bottle

pack_size

string

message.catalog.items[].quantity.unitized.measure.value

Example: 50kg, 500ml

price_kes

number

message.catalog.items[].price.value

Product price

currency

KES

message.catalog.items[].price.currency

Set "KES"

in_stock

boolean

message.catalog.items[].quantity.available.count OR message.catalog.items[].tags[]

Recommended: quantity count

active_ingredient

string/null

message.catalog.items[].tags[].descriptor.code = active_ingredient

Null for seed/fertiliser/equipment

Example Reponse:

{

"context": {

"domain": "agri:input-marketplace",

"action": "on_search",

"version": "1.1.0",

"bap_id": "bap.example.org",

"bpp_id": "bpp.example.org",

"transaction_id": "tx-123456",

"message_id": "msg-123456",

"timestamp": "2026-08-03T12:00:01Z"

},

"message": {

"catalog": {

"items": [

{

"id": "KE-SP-0001-IT-01",

"descriptor": {

"name": "Sorghum Seed Gadam"

},

"category": {

"descriptor": {

"code": "seed"

}

},

"price": {

"currency": "KES",

"value": "345.0"

},

"quantity": {

"unitized": {

"measure": {

"unit": "kg",

"value": "1kg"

}

},

"available": {

"count": 1

}

},

"tags": [

{

"descriptor": {

"code": "crop"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "sorghum"

}

]

},

{

"descriptor": {

"code": "growth_stage"

},

"list": []

},

{

"descriptor": {

"code": "active_ingredient"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": null

}

]

}

]

}

]

}

}

}

Farmers Registry API

Endpoint : GET /farmers/{farmer_id}

API Field

Type

Exact Beckn Field

Remarks

farmer_id

string

message.catalog.items[].id

Farmer unique identifier (KE-FR-#####)

farmer_token

string

message.catalog.items[].tags[].descriptor.code = farmer_token

Opaque UUID passed downstream, not identity

name_masked

string

message.catalog.items[].descriptor.name

Only masked name should be exposed

phone_masked

string

message.catalog.items[].tags[].descriptor.code = phone_masked

Beckn Item has no phone field

county_code

string

message.catalog.items[].location_ids[] OR message.catalog.items[].tags[].descriptor.code = county_code

Prefer location reference

county_name

string

message.catalog.items[].location_ids[] → location.address.state

Denormalised county name

sub_county

string

message.catalog.items[].location_ids[] → location.address.city

Constituency

ward

string

message.catalog.items[].location_ids[] → location.address.locality

Ward

geo_coarse

object

message.catalog.items[].location_ids[] → location.gps

Use coarse location only

aez_code

string

message.catalog.items[].tags[].descriptor.code = aez_code

Domain metadata

farm_size_ha

number

message.catalog.items[].tags[].descriptor.code = farm_size_ha

Domain metadata

land_holdings

object[]

message.catalog.items[].tags[].descriptor.code = land_holdings

Domain extension

crops

object[]

message.catalog.items[].tags[].descriptor.code = crops

Domain extension

livestock

object[]

message.catalog.items[].tags[].descriptor.code = livestock

Domain extension

API Field

Beckn Search Mapping

Remarks

county_code

message.intent.fulfillment.stops[0].location.address.area_code

Administrative area/county code

crop

message.intent.item.descriptor.code

Crop identifier

category

message.intent.item.category.descriptor.code

Fertiliser, Seed, Pesticide etc.

growth_stage

message.intent.item.tags

Custom tag (growth_stage)

item_query

message.intent.item.descriptor.name

Free text search

in_stock_only

message.intent.item.tags

Custom tag (in_stock_only=true)

type

message.intent.provider.categories.descriptor.code or Provider tag

Agrovet, Vet clinic etc.

lat

message.intent.fulfillment.stops[0].location.gps

GPS coordinates

lon

message.intent.fulfillment.stops[0].location.gps

Combined with latitude

radius_km

message.intent.fulfillment.tags

Search radius

limit

message.intent.tags

Pagination metadata

offset

message.intent.tags

Pagination metadata

Crop

API Field

Type

Exact Beckn Field

Remarks

crop_code

CropCode

message.catalog.items[].tags[].descriptor.code = crop_code

Controlled crop code

variety

string

message.catalog.items[].tags[].descriptor.code = variety

Local variety (e.g. H614)

area_ha

number

message.catalog.items[].tags[].descriptor.code = area_ha

Area under cultivation

growth_stage

GrowthStageCode

message.catalog.items[].tags[].descriptor.code = growth_stage

Current crop stage

planting_month

string

message.catalog.items[].tags[].descriptor.code = planting_month

Format YYYY-MM

production_purpose

string | null

message.catalog.items[].tags[].descriptor.code = production_purpose

subsistence/commercial/mixed

production_system

string | null

message.catalog.items[].tags[].descriptor.code = production_system

monocropping/intercropping

uses_certified_seeds

boolean

message.catalog.items[].tags[].descriptor.code = uses_certified_seeds

Boolean metadata

uses_fertilizer

boolean

message.catalog.items[].tags[].descriptor.code = uses_fertilizer

Boolean metadata

uses_pesticides

boolean

message.catalog.items[].tags[].descriptor.code = uses_pesticides

Boolean metadata

water_source

string | null

message.catalog.items[].tags[].descriptor.code = water_source

rain_fed, borehole_pump, etc.

harvest_year

integer | null

message.catalog.items[].tags[].descriptor.code = harvest_year

Expected/actual harvest year

Livestock

API Field

Type

Exact Beckn Field

Remarks

type

string

message.catalog.items[].tags[].descriptor.code = livestock_type

e.g. dairy_cattle, goats, poultry

male_count

integer

message.catalog.items[].tags[].descriptor.code = male_count

Number of male livestock

female_count

integer

message.catalog.items[].tags[].descriptor.code = female_count

Number of female livestock

total_count

integer

message.catalog.items[].tags[].descriptor.code = total_count

Total livestock count

production_system

string | null

message.catalog.items[].tags[].descriptor.code = production_system

zero_grazing, free_range, etc.

uses_ai

boolean

message.catalog.items[].tags[].descriptor.code = uses_ai

Artificial insemination

uses_vaccination

boolean

message.catalog.items[].tags[].descriptor.code = uses_vaccination

Vaccination status

uses_deworming

boolean

message.catalog.items[].tags[].descriptor.code = uses_deworming

Deworming status

production_purpose

string | null

message.catalog.items[].tags[].descriptor.code = production_purpose

dairy, meat, eggs

hive_count

integer | null

message.catalog.items[].tags[].descriptor.code = hive_count

Beekeeping only

hive_type

string | null

message.catalog.items[].tags[].descriptor.code = hive_type

Beekeeping only

active_units

integer | null

message.catalog.items[].tags[].descriptor.code = active_units

Aquaculture ponds/cages

Example Reponse:

{

"context": {

"domain": "agri:farmer-registry",

"action": "on_search",

"version": "1.1.0",

"bap_id": "bap.example.org",

"bpp_id": "bpp.example.org",

"transaction_id": "tx-123456",

"message_id": "ee55d89e-e37f-4bad-b298-ced7b770d1ef",

"timestamp": "2026-07-27T20:56:09.289200+00:00"

},

"message": {

"catalog": {

"locations": [

{

"id": "KE-014",

"gps": "-0.5565,37.414",

"address": {

"state": "Embu",

"city": "Manyatta",

"locality": "Mbeti North"

}

}

],

"items": [

{

"id": "KE-FR-00001",

"descriptor": {

"name": "J*** A*******"

},

"location_ids": [

"KE-014"

],

"tags": [

{

"descriptor": {

"code": "farmer_token"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "3b982ef8-daf6-4a26-946d-3f31fc377a4c"

}

]

},

{

"descriptor": {

"code": "phone_masked"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "+2547*****810"

}

]

},

{

"descriptor": {

"code": "aez_code"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "UM2"

}

]

},

{

"descriptor": {

"code": "farm_size_ha"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": 0.5

}

]

},

{

"descriptor": {

"code": "land_holdings"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": {

"tenure_type": "OWNED_NO_TITLE",

"land_size_hectares": 0.5,

"land_for_crops": 0.5,

"land_for_livestock": 0.0,

"land_for_other": 0.0,

"land_idle": 0.0,

"documentation_status": "untitled",

"parcel_number": null

}

}

]

},

{

"descriptor": {

"code": "crops"

},

"list": [

{

"descriptor": {

"code": "crop_code"

},

"value": "maize"

},

{

"descriptor": {

"code": "variety"

},

"value": "local"

},

{

"descriptor": {

"code": "area_ha"

},

"value": 0.3

},

{

"descriptor": {

"code": "growth_stage"

},

"value": "grain_fill"

},

{

"descriptor": {

"code": "planting_month"

},

"value": "2026-03"

},

{

"descriptor": {

"code": "production_purpose"

},

"value": "subsistence"

},

{

"descriptor": {

"code": "production_system"

},

"value": "intercropping"

},

{

"descriptor": {

"code": "uses_certified_seeds"

},

"value": true

},

{

"descriptor": {

"code": "uses_fertilizer"

},

"value": false

},

{

"descriptor": {

"code": "uses_pesticides"

},

"value": false

},

{

"descriptor": {

"code": "water_source"

},

"value": "canal_system"

},

{

"descriptor": {

"code": "harvest_year"

},

"value": 2026

}

]

},

{

"descriptor": {

"code": "livestock"

},

"list": []

}

]

}

]

}

}

}

Knowledge Search API

Endpoint : GET /api/v1/knowledge/search

API Parameter

Type

Exact Beckn Field

Remarks

q

string

message.intent.item.descriptor.name

Natural-language search query (e.g., "What fertiliser should I use for maize?")

topK

number

message.intent.tags[].descriptor.code = topK

Domain-specific extension for maximum results

domain

string

message.intent.tags[].descriptor.code = domain

Knowledge domain filter (e.g., agronomy)

language

string

message.intent.tags[].descriptor.code = language

Language preference (e.g., en, sw)

Example Payload:

{

"context": {

"domain": "agri:knowledge-base",

"action": "search",

"version": "1.1.0",

"bap_id": "bap.example.org",

"bpp_id": "bpp.example.org",

"transaction_id": "tx-123456",

"message_id": "msg-123456",

"timestamp": "2026-08-03T12:00:00Z"

},

"message": {

"intent": {

"item": {

"descriptor": {

"name": "What fertiliser should I use for maize?"

}

},

"tags": [

{

"descriptor": {

"code": "topK"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "5"

}

]

},

{

"descriptor": {

"code": "domain"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "agronomy"

}

]

},

{

"descriptor": {

"code": "language"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "en"

}

]

}

]

}

}

}

Response

API Field

Type

Beckn Field

Remarks

success

boolean

HTTP Status + message / error

❌ Beckn has no success field. A successful response is indicated by a valid Beckn response (typically HTTP 200 with message). Errors are represented using the error object. (Beckn)

statusCode

number

HTTP Status Code

❌ Not part of the Beckn payload. Keep it at the HTTP protocol layer. (Beckn)

data.query

string

message.catalog.tags[].descriptor.code = "query"

Original query used to retrieve the results. Domain-specific metadata.

data.chunks

array

message.catalog.items[]

Each retrieved knowledge chunk becomes a Beckn Item. (GitExtract)

data.totalFound

number

message.catalog.tags[].descriptor.code = "total_found"

Domain-specific metadata.

data.searchMode

string

message.catalog.tags[].descriptor.code = "search_mode"

Example: hybrid, vector, keyword.

data.latencyMs

number

message.catalog.tags[].descriptor.code = "latency_ms"

Search execution metadata.

traceId

string

context.message_id (preferred)

Correlation identifier for the request/response cycle. Beckn already defines message_id for this purpose. (Beckn)

timestamp

string

context.timestamp

Standard Beckn context field (RFC3339/ISO-8601 timestamp). (Beckn)

Example Reponse:

{

"context": {

"domain": "agri:knowledge-service",

"action": "on_search",

"version": "1.1.0",

"bap_id": "bap.example.org",

"bpp_id": "bpp.example.org",

"transaction_id": "tx-123456",

"message_id": "trace-987654321",

"timestamp": "2026-08-03T12:00:01Z"

},

"message": {

"catalog": {

"items": [

{

"id": "chunk-001",

"descriptor": {

"name": "Knowledge Chunk 1"

},

"tags": [

{

"descriptor": {

"code": "content"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "Apply Nitrogen fertilizer during the vegetative stage of maize for optimal growth."

}

]

}

]

},

{

"id": "chunk-002",

"descriptor": {

"name": "Knowledge Chunk 2"

},

"tags": [

{

"descriptor": {

"code": "content"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "Use DAP fertilizer at planting and CAN fertilizer for top dressing."

}

]

}

]

}

],

"tags": [

{

"descriptor": {

"code": "query"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "What fertiliser should I use for maize?"

}

]

},

{

"descriptor": {

"code": "total_found"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "2"

}

]

},

{

"descriptor": {

"code": "search_mode"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "hybrid"

}

]

},

{

"descriptor": {

"code": "latency_ms"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "145"

}

]

}

]

}

}

}

Open-Meteo Weather API

Endpoint : GET /v1/forecast

API Parameter

Type

Exact Beckn Field

Remarks

latitude

number

message.intent.fulfillment.end.location.gps

GPS format: "latitude,longitude"

longitude

number

message.intent.fulfillment.end.location.gps

Combined with latitude in a single gps field

hourly

string (comma-separated)

message.intent.tags[].descriptor.code = "hourly"

Requested hourly weather variables

daily

string (comma-separated)

message.intent.tags[].descriptor.code = "daily"

Requested daily forecast variables

forecast_days

number

message.intent.tags[].descriptor.code = "forecast_days"

Number of forecast days

API Field

Type

Exact Beckn Field

Remarks

latitude

number

message.catalog.providers[].locations[].gps

Returned model/grid latitude as part of GPS ("lat,lon"). (Beckn)

longitude

number

message.catalog.providers[].locations[].gps

Returned model/grid longitude as part of GPS. (Beckn)

generationtime_ms

number

message.catalog.tags[].descriptor.code = "generationtime_ms"

Weather-provider metadata. (Beckn)

utc_offset_seconds

number

message.catalog.tags[].descriptor.code = "utc_offset_seconds"

Timezone metadata.

timezone

string

message.catalog.tags[].descriptor.code = "timezone"

e.g. Africa/Nairobi.

timezone_abbreviation

string

message.catalog.tags[].descriptor.code = "timezone_abbreviation"

e.g. EAT.

elevation

number

message.catalog.providers[].locations[].tags[].descriptor.code = "elevation"

Elevation of the weather model location.

hourly_units

object

message.catalog.tags[].descriptor.code = "hourly_units"

Units for returned hourly variables.

hourly

object

message.catalog.items[]

Each hourly forecast (or forecast series) represented as catalog items. (Beckn)

Example Reponse:

{

"context": {

"domain": "weather-advisory:oan",

"action": "on_search",

"version": "1.1.0",

"bap_id": "bap.example.org",

"bpp_id": "bpp.example.org",

"transaction_id": "tx-123456",

"message_id": "msg-123456",

"timestamp": "2026-08-03T12:00:01Z"

},

"message": {

"catalog": {

"providers": [

{

"id": "weather-provider-001",

"descriptor": {

"name": "Weather Forecast Service"

},

"locations": [

{

"id": "LOC-001",

"gps": "-1.3005272,36.824646",

"tags": [

{

"descriptor": {

"code": "elevation"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "1677"

}

]

}

]

}

]

}

],

"items": [

{

"id": "hourly-forecast",

"descriptor": {

"name": "Hourly Weather Forecast"

},

"tags": [

{

"descriptor": {

"code": "time"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "[ ... ]"

}

]

},

{

"descriptor": {

"code": "temperature_2m"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "[ ... ]"

}

]

},

{

"descriptor": {

"code": "relative_humidity_2m"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "[ ... ]"

}

]

},

{

"descriptor": {

"code": "dew_point_2m"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "[ ... ]"

}

]

},

{

"descriptor": {

"code": "apparent_temperature"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "[ ... ]"

}

]

},

{

"descriptor": {

"code": "cloud_cover"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "[ ... ]"

}

]

},

{

"descriptor": {

"code": "precipitation"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "[ ... ]"

}

]

},

{

"descriptor": {

"code": "precipitation_probability"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "[ ... ]"

}

]

},

{

"descriptor": {

"code": "soil_temperature_0cm"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "[ ... ]"

}

]

},

{

"descriptor": {

"code": "wind_direction_10m"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "[ ... ]"

}

]

},

{

"descriptor": {

"code": "wind_speed_10m"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "[ ... ]"

}

]

},

{

"descriptor": {

"code": "rain"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "[ ... ]"

}

]

},

{

"descriptor": {

"code": "visibility"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "[ ... ]"

}

]

}

]

}

],

"tags": [

{

"descriptor": {

"code": "generationtime_ms"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "1.2930631637573242"

}

]

},

{

"descriptor": {

"code": "utc_offset_seconds"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "0"

}

]

},

{

"descriptor": {

"code": "timezone"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "GMT"

}

]

},

{

"descriptor": {

"code": "timezone_abbreviation"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "GMT"

}

]

},

{

"descriptor": {

"code": "hourly_units"

},

"list": [

{

"descriptor": {

"code": "value"

},

"value": "{\"time\":\"iso8601\",\"temperature_2m\":\"°C\",\"relative_humidity_2m\":\"%\",\"dew_point_2m\":\"°C\",\"apparent_temperature\":\"°C\",\"cloud_cover\":\"%\",\"precipitation\":\"mm\",\"precipitation_probability\":\"%\",\"soil_temperature_0cm\":\"°C\",\"wind_direction_10m\":\"°\",\"wind_speed_10m\":\"km/h\",\"rain\":\"mm\",\"visibility\":\"m\"}"

}

]

}

]

}

}

}

Last updated