BPP API Documentation

BPP Content API - Product Overview

The CABI BioProtection Portal (BPP) Content API and associated endpoints provide external partners and customers with structured, secure access to BPP registries, enabling the retrieval of registered biocontrol and biopesticide products, as well as crop-pest relationships where biological alternatives are available.

The API is designed to support:

Integration of biopesticide recommendations into third-party agricultural advisory platforms
Dynamic crop and pest filtering scoped by country regulations
Discovery and retrieval of biological products and active substances

Base URL:https://data.cabi.org/bpp

Request Payload Flexibility

For all BPP POST endpoints, only the mandatory parameters listed in the Request Schema tables must be present in your request. Any optional filters or pagination controls can be completely omitted from your request body if they are not needed. You do not need to submit empty placeholder values or defaults for unused parameters.

Authentication

All requests must include your unique API Key in the header.

Header: x-api-key: YOUR_API_KEY

Note: Data access is automatically scoped based on this key. If your entitlements only cover Brazil (BR) and you query for India (IN), you will receive an entitlement authorization error.

GET /countries

Countries with Available BPP Content

Business Purpose

Retrieves the list of countries where the partner has entitlement and bioprotection data exists. Useful for populating country dropdown filters in external applications.

What this endpoint provides

A list of countries where bioprotection products and crop-pest data are available.
Standardized ISO-2 country codes and country names.
Entitlement-scoped results, ensuring partners only receive authorized geographic regions.

Why this matters

Populates country selector UI components dynamically.
Ensures client applications only request data for supported, authorized regions.

Request

curl -X GET "{{BASE_URL}}/countries" \
     -H "x-api-key: YOUR_API_KEY"

POST /crops

Available Crops

Business Purpose

Fetch a list of crops registered for bioprotection products in a specific country. Can be filtered by pest to show only crops that suffer from a specific pest.

What this endpoint provides

A list of crops registered for biological protection products in the specified country.
Unique BPP crop identifiers and crop names in English and the requested language.
Optional filtering by pest IDs to return only crops affected by those specific pests.

Why this matters

Facilitates structured crop selections in search interfaces.
Prevents advisors and growers from selecting unsupported crop-pest combinations.

Request Payload Validation

Only country and language are required in the request payload. Other filters (such as pests and search) and pagination controls (pageSize, pageNo) are optional and can be omitted entirely from the request, or included to filter results. If search is provided, it must contain at least 2 characters.

Translations and the 'All' Crops Group Term

Some products are permitted for use on all crops. The BioProtection Portal uses a group term 'all' to agglomerate all crop terms on our database. Some of the crop terms in the database may not have non-English translations at present. Therefore, a request for crop terms for a specific country in a non-English language may return fewer results than if the request was in English. The correct number of crops is the English-language result, as this truly covers 'all' crops on the system. The count of products (also available via the API 'search' request) remains the same across the languages.

Request Schema

Field	Type	Status	Description
`country`	String	Mandatory	ISO-2 Country Code (e.g., `"br"`)
`language`	String	Mandatory	ISO-2 Language Code (e.g., `"en"`, `"pt"`)
`pests`	Array[Integer]	Optional Filter	List of Pest IDs to filter crops. Supports an integer array with one or multiple values (e.g., `[12331]` or `[12331, 66242]`), or an empty array `[]` to retrieve crops for all entitled pests.
`search`	String	Optional Filter	Search text of crop name (must contain at least 2 characters if provided)
`pageSize`	Integer	Optional	Number of results per page (maximum is 100). The page size assigned to your entitlement will take preference.
`pageNo`	Integer	Optional	Page number (1-based, starts from 1)

Examples

Example 1: Unfiltered crops in country

Queries all entitled crops registered in Brazil in Portuguese.

Note: Optional parameters such as pests, search, pageSize, and pageNo are omitted in this basic request.

curl -X POST "{{BASE_URL}}/crops" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "country": "br",
       "language": "pt"
     }'

Example 2: Filtered by Pest ID

Retrieve crops associated with pest ID 69591463 in Brazil.

curl -X POST "{{BASE_URL}}/crops" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "country": "br",
       "language": "pt",
       "pests": [69591463]
     }'

Example 3: Filtered by Multiple Pest IDs

Retrieve crops associated with pest IDs 69591463 and 11850824.

curl -X POST "{{BASE_URL}}/crops" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "country": "br",
       "language": "pt",
       "pests": [69591463, 11850824]
     }'

POST /pests

Available Pests

Business Purpose

Fetch pests registered for bioprotection products in a specific country. Can be filtered by crops to show only pests affecting a specific crop.

What this endpoint provides

A list of pests registered for bioprotection products in the specified country.
Unique BPP pest identifiers and pest names in English and the requested language.
Optional filtering by crop IDs to return only pests that affect those specific crops.

Why this matters

Facilitates structured pest selections in search interfaces.
Helps agricultural advisors identify target pests within a specific crop context.

Request Payload Validation

Only country and language are required in the request payload. Other filters (such as crops and search) and pagination controls (pageSize, pageNo) are optional and can be omitted entirely from the request, or included to filter results. If search is provided, it must contain at least 2 characters.

Request Schema

Field	Type	Status	Description
`country`	String	Mandatory	ISO-2 Country Code (e.g., `"br"`)
`language`	String	Mandatory	ISO-2 Language Code (e.g., `"en"`, `"pt"`)
`crops`	Array[Integer]	Optional Filter	List of Crop IDs to filter pests. Supports an integer array with one or multiple values (e.g., `[15395]` or `[15395, 29222]`), or an empty array `[]` to retrieve pests for all entitled crops.
`search`	String	Optional Filter	Search text of pest name (must contain at least 2 characters if provided)
`pageSize`	Integer	Optional	Number of results per page (maximum is 100). The page size assigned to your entitlement will take preference.
`pageNo`	Integer	Optional	Page number (1-based, starts from 1)

Examples

Example 1: Unfiltered pests in country

Queries all entitled pests registered in Kenya in English.

Note: Optional parameters such as crops, search, pageSize, and pageNo are omitted in this basic request.

curl -X POST "{{BASE_URL}}/pests" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "country": "ke",
       "language": "en"
     }'

Example 2: Filtered by Crop ID

Retrieve pests associated with Tomato (Crop ID 43277469) in Kenya.

curl -X POST "{{BASE_URL}}/pests" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "country": "ke",
       "language": "en",
       "crops": [43277469]
     }'

Example 3: Filtered by Multiple Crop IDs

curl -X POST "{{BASE_URL}}/pests" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "country": "ke",
       "language": "en",
       "crops": [43277469, 56887294]
     }'

POST /search

Bioprotection Products Search

Business Purpose

Searches and retrieves summary information for registered biological control and biopesticide products matching biological filters (crops, pests), textual keywords, and geographical scope.

What this endpoint provides

A list of biological control and biopesticide products matching the query filters.
Product summary details (e.g., product name, registration number, active ingredients, manufacturer).
Search results filtered by country, language, crop, pest, and/or text query.
Entitlement-scoped pagination using pageSize and pageNo.

Why this matters

Powers product discovery and recommendation search bars.
Integrates direct biocontrol suggestions into third-party advisory tools and apps.

Request Payload Validation

Only country and language are required in the request payload. Other filters (such as crops and pests), sorting options (sortBy, sortDirection), and pagination controls (pageSize, pageNo) are optional and can be omitted entirely from the request, or included to filter results.

Request Schema

Field	Type	Status	Description
`country`	String	Mandatory	ISO-2 Country Code (e.g., `"br"`)
`language`	String	Mandatory	ISO-2 Language Code (e.g., `"en"`, `"pt"`)
`crops`	Array[Integer]	Optional Filter	List of Crop IDs. Supports an integer array with one or multiple values (e.g., `[15395]` or `[15395, 29222]`), or an empty array `[]` to retrieve products for all entitled crops.
`pests`	Array[Integer]	Optional Filter	List of Pest IDs. Supports an integer array with one or multiple values (e.g., `[12331]` or `[12331, 66242]`), or an empty array `[]` to retrieve products for all entitled pests.
`pageSize`	Integer	Optional	Number of results per page (maximum is 100). The page size assigned to your entitlement will take preference.
`pageNo`	Integer	Optional	Page number (1-based, starts from 1)
`sortBy`	String	Optional	Field to sort by (e.g., `"productName"`, `"lastUpdated"`). Default is `"productName"`.
`sortDirection`	String	Optional	Sort direction (e.g., `"asc"`, `"desc"`). Default is `"asc"`.

Examples

Example 1: Basic search in country with paging and sorting

Search for products in Brazil with page size 10, page number 1, sorted by name.

Note: Optional biological filters (crops, pests) are omitted in this query.

curl -X POST "{{BASE_URL}}/search" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "country": "br",
       "language": "pt",
       "pageSize": 10,
       "pageNo": 1,
       "sortBy": "productName",
       "sortDirection": "asc"
     }'

Example 2: Filter search by Crop ID and Pest ID

Narrow down products targeting Mango crops (43277469) and pest Damping off (22018682) in Brazil.

curl -X POST "{{BASE_URL}}/search" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "country": "br",
       "language": "pt",
       "crops": [43277469],
       "pests": [22018682]
     }'

Example 3: Search with Multiple Crop and Pest IDs

curl -X POST "{{BASE_URL}}/search" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "country": "br",
       "language": "pt",
       "crops": [43277469, 37956406],
       "pests": [22018682, 95755047]
     }'

POST /product

Retrieve Product Details

Business Purpose

Retrieves the complete, detailed metadata of a specific bioprotection product using its unique product identifier.

What this endpoint provides

Full details and metadata for a single bioprotection product using its unique product ID.
Comprehensive information including active substances, application rates, target crops/pests, safety guidelines, and manufacturer details.

Why this matters

Powers the detailed product view screen, explaining how to correctly source and apply biological products.
Enables integration of detailed product labels and registry data into farm management systems.

Request Payload Validation

Only country, language, and productId are required in the request payload. No other fields are supported.

Request Schema

Field	Type	Status	Description
`country`	String	Mandatory	ISO-2 Country Code (e.g., `"br"`)
`language`	String	Mandatory	ISO-2 Language Code (e.g., `"en"`, `"pt"`)
`productId`	String	Mandatory	Unique Product ID/Code (e.g., `"12345"`)

Request Example

Note: All parameters in this schema are mandatory.

curl -X POST "{{BASE_URL}}/product" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "country": "br",
       "language": "pt",
       "productId": "51181174"
     }'

API Principles

All BPP Content API endpoints share the following characteristics:

Security

Access is controlled via API keys, with protections against malicious queries.

Consistency

Responses use a consistent JSON structure across all endpoints.

Performance

Designed for efficient response times, even with complex geographic and biological filters applied.

Reliability

Intended for production use by external partners and agricultural platforms.

Typical Customer Journey

Retrieve active country filters.
Fetch available crops and pests for a chosen country.
Search for bioprotection products using crop/pest filters.
Retrieve specific product details using a selected product ID.

Error Codes

Status	Meaning
`400`	Bad Request: Invalid request JSON, schema validation failure, or missing required fields.
`403`	Access Denied: API Key missing, invalid, or query parameter (e.g. countryCode) violates your entitlement policy.
`404`	Not Found: The requested resource, path, or query ID does not exist in your scoping.
`500`	Internal Server Error: An error occurred on the server side.

Appendix

CABI BioProtection Portal (BPP)

The CABI BioProtection Portal is the ground-breaking information resource that helps growers and agricultural advisors to identify, source and correctly apply biocontrol and biopesticide products against agricultural pests in their crops. More information about our mission, partners, and team is available on the CABI BioProtection Portal About Us page.