Trait data API
The trait data API provides a 4-step workflow to retrieve phenotypic trait observations from Genesys. You start by finding trait datasets associated with filtered accessions, then retrieve the available trait columns, fetch the actual observations, and finally get the descriptor metadata.
See the Authentication guide for details about authenticating your API calls.
Workflow overview
The process follows these steps:
- Find datasets - Get trait dataset UUIDs for filtered accessions
- List trait columns - Retrieve dataset structure with available trait column UUIDs
- Fetch trait data - Extract actual trait observations for specified fields
- Get descriptors - Retrieve metadata about the trait descriptors
1. Get trait datasets
This endpoint returns dataset UUIDs associated with accessions matching your passport data filters.
Request URL
https://api.genesys-pgr.org/api/v2/dataset/accessions-datasets
Request headers
| Header | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Bearer <access_token> |
Request body
Uses the same filter structure as the passport data API.
{
"crop": ["rice"],
"historic": false,
"institute": {
"code": ["PHL001"]
}
}
Example cURL request
curl --location 'https://api.genesys-pgr.org/api/v2/dataset/accessions-datasets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data '{
"crop": ["rice"],
"historic": false,
"institute": {"code": ["PHL001"]}
}'
Response
Returns an array of dataset UUIDs:
[
"81bab6b6-6592-4a9d-968b-2eb1058f18cd",
"567b14d8-7721-481b-9b90-e252cb747031"
]
2. List available trait columns
This endpoint retrieves the structure of the trait datasets, including all available trait column UUIDs. Use these column UUIDs in the next step to fetch specific trait data.
Request URL
https://api.genesys-pgr.org/api/v2/amphibian/datatable/list
Request headers
| Header | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Bearer <access_token> |
Request body
Pass the dataset UUIDs returned from Step 1 as a JSON array.
[
"81bab6b6-6592-4a9d-968b-2eb1058f18cd",
"567b14d8-7721-481b-9b90-e252cb747031"
]
Example cURL request
curl --location 'https://api.genesys-pgr.org/api/v2/amphibian/datatable/list' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data '[
"81bab6b6-6592-4a9d-968b-2eb1058f18cd",
"567b14d8-7721-481b-9b90-e252cb747031"
]'
Response
Returns an array of dataset objects. The columns key contains UUID references for each trait descriptor.
[
{
"id": "644bc280b777ea11fa97518c",
"version": 37,
"key": "567b14d8-7721-481b-9b90-e252cb747031",
"title": "Evaluation",
"collection": "amphibian.567b14d8-7721-481b-9b90-e252cb747031",
"columns": {
"5b60bd43-a268-48c6-9eae-f12d8d4539ca": {},
"a6a7853b-b698-4faa-896a-2acdf47a1d1d": {}
}
}
]
3. Fetch trait data
This endpoint retrieves the actual trait observations from the specified datasets. You provide the dataset UUIDs, the specific trait column UUIDs you want, and passport data filters.
Request URL
https://api.genesys-pgr.org/api/v2/dataset/data
Query parameters
| Parameter | Value | Description |
|---|---|---|
| l | 1000 | Number of records returned (default: 100, maximum: 1,000) |
| datasetUuids | Comma-separated UUIDs | Dataset UUIDs from Step 1 |
| fields | Comma-separated UUIDs | Trait column UUIDs from Step 2 |
Request headers
| Header | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Bearer <access_token> |
Request body
{
"filters": {
"crop": ["rice"],
"historic": false,
"institute": {"code": ["PHL001"]}
}
}
Example cURL request
curl --location 'https://api.genesys-pgr.org/api/v2/dataset/data?datasetUuids=81bab6b6-6592-4a9d-968b-2eb1058f18cd&fields=5b60bd43-a268-48c6-9eae-f12d8d4539ca,a6a7853b-b698-4faa-896a-2acdf47a1d1d' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data '{
"filters": {
"crop": ["rice"],
"historic": false,
"institute": {"code": ["PHL001"]}
}
}'
Response
Returns a JSON object containing trait values for each accession and the selected fields. Field names are referenced by their UUIDs from the descriptor metadata.
4. Get descriptor details
The trait data returned in Step 3 uses UUIDs to reference descriptors. This endpoint retrieves the full metadata for those descriptors, including the trait names, units, and descriptions.
Request URL
https://api.genesys-pgr.org/api/v2/descriptor/list/details
Request headers
| Header | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Bearer <access_token> |
Request body
{
"uuid": [
"a70f4f05-1bfb-4fa3-b6a5-24ab2bc8f5ff",
"7acea795-0d65-4456-9717-8f930ecb4f98"
]
}
Example cURL request
curl --location 'https://api.genesys-pgr.org/api/v2/descriptor/list/details' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data '{
"uuid": [
"a70f4f05-1bfb-4fa3-b6a5-24ab2bc8f5ff",
"7acea795-0d65-4456-9717-8f930ecb4f98"
]
}'
Response
Returns descriptor metadata objects that explain what each UUID represents.
This guide was authored by Khadija Aouzal (ICARDA).