Passport data API

Genesys offers two endpoints to retrieve passport data. Both accept the same filters but return data in different formats and with very different performance characteristics.

Best for bulk export

Use /acn/query for downloading large datasets. It can return up to 1,000,000 records per request, making it the fastest way to export passport data. Genesys holds over 4.5 million accession records, so you would need just a handful of paginated requests to fetch everything.

Use /acn/filter only when you need the full JSON response with all fields. It is limited to 1,000 records per request, which would require thousands of requests to download the entire dataset.

See the Authentication guide for details about authenticating your API calls.

/acn/query endpoint

The /acn/query endpoint provides high-performance bulk export of accession passport data, supporting up to 1,000,000 records per request. It returns a CSV file containing the requested passport data. With over 4.5 million accession records in Genesys, a single request with l=1000000 can fetch roughly a quarter of the entire dataset.

Request URL

https://api.genesys-pgr.org/api/v2/acn/query

Query parameters

Parameter	Value	Description
p	0	Page number (zero-indexed)
l	100000	Number of records returned per page (maximum: 1,000,000)
select	Comma-separated list	Fields to include in the response

Select fields

The select parameter accepts a comma-separated list of fields to include in the response. Each field uses the format <genesys field name>( <csv header alias>)?. The alias is optional and sets the column header in the CSV output.

Performance

Requesting only the fields you need improves response times significantly.

MCPD (CSV header)	Genesys field	Description
INSTCODE	instituteCode	FAO WIEWS institute code
ACCENUMB	accessionNumber	Accession number within the genebank
DOI	doi	Digital Object Identifier assigned to the material
HISTORIC	historic	Historic accession flag
CURATION	curationType	Curation type
GENUS	taxonomy.genus	Genus name
SPECIES	taxonomy.species	Species epithet
SPAUTHOR	taxonomy.spAuthor	Species authority
SUBTAXA	taxonomy.subtaxa	Subtaxon
SUBTAUTHOR	taxonomy.subtAuthor	Subtaxon authority
GRIN_TAXON_ID	taxonomy.currentTaxonomySpecies.id	GRIN taxonomy ID
GRIN_NAME	taxonomy.currentTaxonomySpecies.name	GRIN taxonomy name
GRIN_AUTHOR	taxonomy.currentTaxonomySpecies.nameAuthority	GRIN taxonomy authority
CROPNAME	cropName	Common crop name
CROPCODE	crop.shortName	Crop code
SAMPSTAT	sampStat	Biological status of accession
ACQDATE	acquisitionDate	Acquisition date
ACCENAME	accessionName	Accession name
ORIGCTY	origCty	Country of origin
COLLSITE	coll.collSite	Location of collecting site
DECLATITUDE	latitude	Decimal latitude
DECLONGITUDE	longitude	Decimal longitude
COORDUNCERT	coordinateUncertainty	Coordinate uncertainty (m)
COORDDATUM	coordinateDatum	Coordinate datum
GEOREFMETH	georeferenceMethod	Georeferencing method
ELEVATION	elevation	Elevation (masl)
COLLDATE	coll.collDate	Collecting date
COLLSRC	coll.collSrc	Collecting/acquisition source
COLLNUMB	coll.collNumb	Collecting number
COLLCODE	coll.collCode	Collecting institute code
COLLNAME	coll.collName	Collecting institute name
COLLINSTADDRESS	coll.collInstAddress	Collecting institute address
COLLMISSID	coll.collMissId	Collecting mission identifier
DONORCODE	donorCode	Donor institute code
DONORNAME	donorName	Donor institute name
DONORNUMB	donorNumb	Donor accession number
OTHERNUMB	aliases.name	Other identifiers
BREDCODE	breederCode	Breeding institute code
BREDNAME	breederName	Breeding institute name
ANCEST	ancest	Ancestral data
DUPLSITE	duplSite	Location of safety duplicates
STORAGE	storage	Type of germplasm storage
MLSSTAT	mlsStatus	MLS status
ACCEURL	acceUrl	Accession URL
REMARKS	remarks	Remarks
DATAPROVIDERID	dataProviderId	Data provider ID
PDCI	pdci.score	Passdata Data Completeness Index score
UUID	uuid	Universally unique identifier
LASTMODIFIED	lastModifiedDate	Last modified date

Examples

To request only the institute code, accession number, coordinates, and sample status:

Without aliases, CSV headers use the Genesys field names:

select=instituteCode,accessionNumber,latitude,longitude,sampStat

With aliases, CSV headers use the MCPD names you specify:

select=instituteCode INSTCODE,accessionNumber ACCENUMB,latitude DECLATITUDE,longitude DECLONGITUDE,sampStat SAMPSTAT

Request headers

Header	Value
Content-Type	application/json
Accept	text/csv
Authorization	Bearer <access_token>

Request body

Filters the results. Uses the same structure as the filter endpoint.

{
  "crop": ["barley"],
  "historic": false,
  "institute": {
    "code": ["LBN002"]
  }
}

Example cURL request

curl --location 'https://api.genesys-pgr.org/api/v2/acn/query?p=0&l=1000&select=instituteCode%20INSTCODE%2CaccessionNumber%20ACCENUMB' \
  --header 'Accept: text/csv' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --data '{"crop": ["barley"], "historic": false, "institute": {"code": ["LBN002"]}}'

/acn/filter endpoint

The /acn/filter endpoint returns accession data in JSON for the specified filters. With a maximum of 1,000 records per request, downloading the full dataset of 4.5+ million accessions would require thousands of requests and significant time.

Evaluate first!

Before you opt for this method, check if it provides any additional data that is not available in /acn/query. Use it only when you really need the missing information.

Request URL

https://api.genesys-pgr.org/api/v2/acn/filter

Query parameters

Parameter	Value	Description
p	0	Page number (zero-indexed)
l	1000	Number of records returned (default: 100, maximum: 1,000)

Request headers

Header	Value
Content-Type	application/json
Authorization	Bearer <access_token>

Request body

Filters the results. Uses the same structure as the query endpoint.

{
  "crop": ["barley"],
  "historic": false,
  "institute": {
    "code": ["LBN002"]
  }
}

Example cURL request

curl --location 'https://api.genesys-pgr.org/api/v2/acn/filter' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --data '{
    "crop": ["barley"],
    "historic": false,
    "institute": {
      "code": ["LBN002"]
    }
  }'

Response

Returns a JSON object in the standard paginated format containing an array of AccessionDTO objects.

---

This guide was authored by Khadija Aouzal (ICARDA).