Search API v1 → v2 mapping

Migrating from v1 to v2 involves updating your endpoint URLs to call the new v2 version and modifying your applications to account for breaking changes introduced in v2.

The RCSB PDB Search API v1 was deprecated on April 13, 2022. The final removal of this version will occur on July 13, 2022 at which point queries to https://search.rcsb.org/rcsbsearch/v1/query will no longer work. Programmatic users must adapt queries to be compatible with v2 and use a new version in the requests URLs by July 13, 2022.

Search Request

Here's a mapping of how v1 search queries map to v2:

Text Attribute Search Parameters

Use the range operator instead of the deprecated range_closed operator

v1	v2

The range operator no longer accepts an array of values as an input. Use an object notation to query ranges

v1	v2

Strucmotif Search Parameters

If you used this search API to search for structure motifs, refer to this list of breaking changes in strucmotif query parameters:

whitelist is renamed to allowed_structures
blacklist is renamed to excluded_structures
empty arrays are disallowed

v1	v2

Structure and Strucmotif Search File Upload Parameters

File upload parameters for structure and strucmotif services have changed:

file is renamed to data
file_format is renamed to format
gzipped is removed
ccp4 format is no loner supported

v1	v2

Request Options

Pagination

If you used request_options to paginate through the search results, note that the pager parameter is renamed to paginate

v1	v2

Faceted Queries

If you used the filtering capabilities for faceted (aggregated) search queries, you need to change your applications to account for the following changes:

The filter parameter is removed from Terms Facet, Histogram Facet, Date Histogram Facet, Range Facet, Date Range Facet, and Cardinality Facet. Use a dedicated Filter Facet to obtain the aggregations relevant to the search query
The search query syntax in the filter context of the Filter Facet fully supports boolean operations

v1	v2

Following parameters were removed from the faceted (aggregated) search queries:

max_num_intervals is removed from Histogram Facet, Date Histogram Facet, Range Facet, Date Range Facet
min_interval_population is removed from Range Facet, Date Range Facet
min_interval_population default is changed from 0 to 1

Aggregation name parameter was added to faceted (aggregated) search queries. This property is required:

v1	v2

Results Metadata

The results_verbosity parameter default changed from verbose to minimal. Additional metadata will no longer be returned by default and search results will be represented by the identifier and a total score only. Set results_verbosity to verbose to match an old behavior

v1	v2

Search Response

Here's a mapping of how v1 search response maps to v2:

Faceted queries response

If you used faceted (aggregated) search queries, refer to this list of breaking changes:

drilldown is renamed to facets
groups is renamed to buckets
attribute is renamed to name
distinct_count is renamed to value (cardinality facet response)

v1	v2

Contact Us

Contact info@rcsb.org with questions or feedback about this service.