Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/catalog/) # Catalog API The Catalog API implements the [STAC Specification](https://stacspec.org/), describing geospatial information about the data collections you have access to. ## API Reference API Reference for Catalog is available as an [OpenAPI description](https://docs.planet.com/develop/apis/catalog/reference.md). Simple search request for Sentinel-1 GRD with a bounding box (the coordinate reference system of the values is WGS84 longitude/latitude), available on 10th December 2019. * Python SDK ``` data = { "bbox": [13, 45, 14, 46], "datetime": "2019-12-10T00:00:00Z/2019-12-10T23:59:59Z", "collections": ["sentinel-1-grd"], "limit": 5, } url = "https://services.sentinel-hub.com/catalog/v1/search" response = requests.post(url, json=data) ``` ## Authentication For information about how to authenticate with the Catalog API, see the [Authentication chapter](https://docs.planet.com/develop/authentication.md#sentinel-hub-authentication). ## Rate Limiting The Catalog API follows the general rate limiting policies described in [Rate Limiting](https://docs.planet.com/develop/rate-limiting.md). ## Deployments | Deployment | API endpoint | Region | | ------------------ | ------------------------------------------------------ | ------------ | | AWS EU (Frankfurt) | | eu-central-1 | | AWS US (Oregon) | | us-west-2 | ## Pagination Executing the request specified above returns search context fields at the end of the response, for example: * JSON ``` { "context": { "next": 5, "limit": 5, "returned": 5 } } ``` The presence of the `next` attribute indicates there is more data available for this query, but the server chose to only return 5 results, because the `limit` specified was `5`. If `limit` is not specified, default value is `10`. To query the next page of items, the request needs to include the `next` attribute with its value in the query, for example: * Python SDK ``` data = { "bbox": [13, 45, 14, 46], "datetime": "2019-12-10T00:00:00Z/2019-12-10T23:59:59Z", "collections": ["sentinel-1-grd"], "limit": 5, "next": 5, } url = "https://services.sentinel-hub.com/catalog/v1/search" response = requests.post(url, json=data) ``` The response includes the next page of items; in this case there is no `next` token in `context`, meaning no more items exist for this query. ## Extensions ### Filter The search endpoint by default only accepts the parameters described in [OpenAPI](https://docs.planet.com/develop/apis/catalog/reference.md#tag/catalog_item_search/operation/postCatalogItemSearch). The Filter extension enables users to specify an additional parameter to filter on, while searching through data. The syntax for `filter` is [CQL2](https://docs.ogc.org/is/21-065r2/21-065r2.html): * JSON ``` { "filter": { "op": "", "args": [ { "property": "" }, "" ] }, "filter-lang": "cql2-json" } ``` It is also possible to use simple cql2-text: * JSON ``` { "filter": "eo:cloud_cover > 90" } ``` The available operators are `eq`, `neq`, `lt`, `lte`, `gt`, `gte` and `between`. Only `and` is currently supported as a logical operator. Be careful - different collections have different properties for the query filter available. The information describing this is available inside the documentation for each specific collection (for exanple, [Sentinel-1 GRD](https://docs.planet.com/data/public-data/copernicus/sentinel-1-grd.md)). ### Fields By default, the search endpoint returns all the available attributes of each item. The `fields` extension provides a way for the client to specify which attributes should not be part of the output, making it easy for the client to not have to deal with unnecessary data. Syntax for the `fields` is: * JSON ``` { "fields": { "include": ["", ""], "exclude": ["", "", ""] } } ``` #### Include/Exclude behaviour * When the `fields` attribute is not specified in the request, all the available attributes will be included in the response. * If the `fields` attribute is specified with an empty object, or both `include` and `exclude` are set to null or an empty array is returned, the attributes for each item will be as if `include` was set to a default set of `["id", "type", "geometry", "bbox", "links", "assets", "properties.datetime"]`. * If only `include` is specified, the attributes in `include` will be merged with the default set above. * If only `exclude` is specified, the attributes in `exclude` will be removed from the default set above. * If both `include` and `exclude` are specified, the rule is that an attribute must be included in and not excluded from the response. ### Distinct Sometimes we do not want to search for product metadata, but we want some general information about the product. For example, which acquisition dates are available for Sentinel-1 inside the specified `bbox` and time interval. The `distinct` attribute inside a search request makes this possible. Syntax for `distinct` attribute is: * JSON ``` { "distinct": "" } ``` As with the `filter` attribute, `distinct` is also a collection limited to some specific properties. Information describing these properties can be found inside each collection's documentation (for example, [Sentinel-1 GRD](https://docs.planet.com/data/public-data/copernicus/sentinel-1-grd.md)).