Search data releases using the Globus Search API.

This endpoint performs searches against the Data Release search index and returns matching data releases. The endpoint accepts a Globus Search query document and returns results organized by publication status (published vs draft).

Composing a Search Query

The query parameter must be a valid Globus Search query document. At minimum, it should contain a q field with the search query string. For more advanced queries, you can use filters, sorting, and pagination.

Basic Query Structure

.. code-block:: json

{
    "q": "search terms",
    "limit": 10,
    "offset": 0
}

Query Fields

• q (string, required): The search query string. Supports full-text search across indexed fields. Use * for wildcard matching.

• limit (integer, optional): Maximum number of results to return. Default is 10.

• offset (integer, optional): Number of results to skip for pagination. Default is 0.

• filters (array, optional): Array of filter objects to narrow results. Each filter specifies a field name, comparison operator, and value(s).

• facets (array, optional): Array of facet objects to aggregate results by field values.

• sort (array, optional): Array of sort objects to order results. Each object specifies a field name and sort direction.

Filter Examples

Filter by title (partial match):

.. code-block:: json

{
    "q": "*",
    "filters": [
        {
            "type": "match_all",
            "field_name": "title",
            "values": ["water quality"]
        }
    ]
}

Filter by keyword:

.. code-block:: json

{
    "q": "*",
    "filters": [
        {
            "type": "match_all",
            "field_name": "keywords",
            "values": ["hydrology", "streamflow"]
        }
    ]
}

Filter by date range:

.. code-block:: json

{
    "q": "*",
    "filters": [
        {
            "type": "range",
            "field_name": "usgsCreated",
            "values": [
                {
                    "from": "2023-01-01",
                    "to": "2023-12-31"
                }
            ]
        }
    ]
}

Sorting Examples

Sort by publication date (newest first):

.. code-block:: json

{
    "q": "*",
    "sort": [
        {
            "field_name": "usgsModified",
            "order": "desc"
        }
    ]
}

Faceting Examples

Get counts by keyword:

.. code-block:: json

{
    "q": "*",
    "facets": [
        {
            "name": "keyword_counts",
            "field_name": "keyword.concept",
            "type": "terms",
            "size": 10
        }
    ]
}

When facets are included in the query, the response will contain a facet_results field with aggregation data. Example facet results:

.. code-block:: json

{
    "facet_results": [
        {
            "name": "keyword_counts",
            "buckets": [
                {
                    "value": "hydrology",
                    "count": 145
                },
                {
                    "value": "water quality",
                    "count": 98
                },
                {
                    "value": "streamflow",
                    "count": 76
                }
            ]
        }
    ]
}

Each bucket contains a value (the field value) and count (number of documents with that value).

Complete Query Example

.. code-block:: json

{
    "q": "water quality",
    "limit": 20,
    "offset": 0,
    "filters": [
        {
            "type": "match_all",
            "field_name": "keyword.concept",
            "values": ["Aquifers"]
        },
        {
            "type": "range",
            "field_name": "usgsCreated",
            "values": [
                {
                    "from": "2023-01-01",
                    "to": "*"
                }
            ]
        }
    ],
    "sort": [
        {
            "field_name": "usgsCreated",
            "order": "desc"
        }
    ]
}

Response Format

The response contains search results organized by publication status, along with pagination metadata.

Response Structure

.. code-block:: json

{
    "data": {
        "published": [<published_documents>],
        "draft": [<draft_documents>]
    },
    "facet_results": [<facet_results>]
    "count": 15,
    "has_next_page": true,
    "offset": 0,
    "total": 127,
}

Note: The facet_results field is only present when facets are included in the query.

Response Fields

• data.published (array): Array of published data release documents. Each document contains the full data release metadata including title, description, creators, contributors, publication date, files, and more.

• data.draft (array): Array of draft data release documents. These are unpublished releases that are visible based on the user's permissions.

• facet_results (array, optional): Array of facet aggregation results. Only present when facets are included in the query. Each facet result contains the facet name and buckets with counts for each unique value.

• count (integer): Number of results returned in this response.

• has_next_page (boolean): Whether more results are available beyond this page.

• offset (integer): The offset value used for this request (number of results skipped).

• total (integer): Total number of results matching the query across all pages.

Authentication

Authentication is optional for this endpoint.

• Without authentication: Only publicly visible (published) data releases are returned.

• With authentication: Results include published releases plus draft releases that the authenticated user has permission to view based on their group memberships.

To authenticate, include a bearer token in the Authorization header:

.. code-block::

Authorization: Bearer <access_token>

Error Handling

If the query is invalid or malformed, the endpoint will return a 400 Bad Request error with the message:

"The Globus Search query was not valid. See https://docs.globus.org/api/search/reference/post_query/ for query syntax."

Additional Resources

For complete Globus Search query syntax and capabilities, see: https://docs.globus.org/api/search/reference/post_query/

:param query: A Globus Search query document (dict) containing search parameters :param token: Optional bearer token for authentication :return: Search results with data releases organized by publication status