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
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",
"bap_uri": "https://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)
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