---
title: "Post Search"
method: POST
path: "/datacatalog/api/data-release/search"
tags: ["Data Release"]
---

# Post Search

`POST /datacatalog/api/data-release/search`

## Request

- Base URL: `https://data.usgs.gov` (the document declares no server; this is the origin it was published from)
- URL: `https://data.usgs.gov/datacatalog/api/data-release/search`
- Auth: OAuth 2
  - Authorization code: `https://auth.globus.org/v2/oauth2/authorize?scope=openid`
  - Token URL: `https://data.usgs.gov/datacatalog/api/auth/login`

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

## Request body

- object

## Response `200`

Successful Response

- unknown

## Other responses

- `404`: Not found
- `422`: Validation Error

---

[API](https://skmtc.dev/usgs/apis/usgs-science-data-catalog-api-documentation.md) - [All operations](https://skmtc.dev/usgs/apis/usgs-science-data-catalog-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/usgs/apis/usgs-science-data-catalog-api-documentation/revisions/f5f6a07ba13f?raw)