swagger: '2.0'
info:
title: CMR Search Capabilities Collections API
version: 1.0.0
description: CMR Search API
host: cmr.earthdata.nasa.gov
basePath: /search
schemes:
- https
consumes: []
produces: []
tags:
- name: Collections
description: Collection Search
paths:
/collections{response_format}:
get:
description: '<p>The collection search route supports both GET and POST with URL encoded form data. All parameters are searched in a case insensitive manner.</p><h4> Paging Details </h4>
<p>The CMR contains many more results than can be returned in a single response so the number of results that can be returned is limited. The parameters `page_num`, `offset`, and `page_size` along with the sort specified by `sort_key` control which items will be returned. The query parameter `page_size`, defaulting to 10, controls the amount of items that will be returned in a response. One of `page_num` or `offset` can be provided to index into the search results.
`page_num`, defaulting to 1, chooses a "page" of items to return. If a search matched 50 items the parameters <code>page=3&page_size=5</code> would return the 11th item through the 15th item.
`offset` is a 0 based index into the result set of a query. If a search matched 50 items the parameters <code>offset=3&page_size=5</code> would return 4th result through the 8th result.
You can not page past the 1 millionth item. Please contact the CMR Team at cmr-support@nasa.gov if you need to retrieve items in excess of 1 million from the CMR.</p>
<h4> Parameter Options </h4>
<p>The behavior of search with respect to each parameter can be modified using the `options` parameter. The `options` parameter takes the following form:
`options[parameter][option_key]=value` where parameter is the URL parameter whose behavior is to be affected, value is either `true` or `false`, and `option_key` is one of the following:</p> <ul><li>`ignore_case` - if set to true, the search will be case insensitive and if set to false, the search will be case sensitive. Defaults to true.</li><li> `pattern` - if set to true, the search will treat the value provided for the parameter as a pattern with wild-cards, in which ''*****'' matches zero or more characters and ''?'' matches any single character. For example, <code>platform[]=AB?D*****&options[platform][pattern]=true</code> would match ''ABAD123'', ''ABCD12'', ''ABeD'', etc. Defaults to false. NOTE: Patterns with leading wildcards, like "*****ODIS", are computationally expensive. The CMR limits the maximum number of patterns with a leading wildcard per query to 5.</li><li> `and` - if set to true and if multiple values are listed for the param, the concepts must have ALL of these values in order to match. The default is `false` which means concepts with ANY of the values match. This option only applies to fields which may be multivalued; these are documented here.</li><li> `or` - this option only applies to granule attributes or science-keywords searches. If set to true, attribute searches will find granules that match any of the attributes. The default is false.</li></ul>'
summary: Search for collections
x-no-doc: false
tags:
- Collections
parameters:
- in: path
name: response_format
description: Select an extension to specify the format for search results. The default is xml. An accept header MIME type can also be used to specify the response format. The default is 'application/xml'.
required: false
type: string
default: .xml
enum:
- .xml
- .json
- .atom
- .native
- .umm_json
- .echo10
- .dif10
- .dif
- .iso
- .iso19115
- .opendata
- .kml
- .csv
- in: query
name: keyword
description: <p>Matches collections against a free text keyword search. Keyword searches are case insensitive and support wild cards ? and *.</p>
required: false
type: string
- in: query
name: concept_id[]
description: '<p>A CMR concept id is in the format <code><concept-type-prefix> <unique-number> "-"<provider-id></code></p>
<ul>
<li><code>concept-type-prefix</code> is a single capital letter prefix indicating the concept type. "C" is used for collections</li>
<li><code>unique-number</code> is a single number assigned by the CMR during ingest.</li>
<li><code>provider-id</code> is the short name for the provider. i.e. "LPDAAC_ECS"</li>
</ul>
<p>Example: <code>C123456-LPDAAC_ECS</code></p>'
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: entry_id[]
description: Matches collections by entry ID.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: entry_title[]
description: Matches collections by entry title.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: short_name[]
description: Matches collections by short name.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: version[]
description: Matches collections by version ID.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: provider[]
description: Matches collections by provider ID.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: provider_short_name[]
description: Matches collections by provider short name. Does not support the pattern option.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: science_keywords[0][category]
description: Matches collections by science keyword subfield category. To specify multiple different science keywords use a different index for each science keyword (e.g. science_keywords[1][category]).
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: science_keywords[0][topic]
description: Matches collections by science keyword subfield topic. To specify multiple different science keywords use a different index for each science keyword (e.g. science_keywords[1][topic]).
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: science_keywords[0][term]
description: Matches collections by science keyword subfield term. To specify multiple different science keywords use a different index for each science keyword (e.g. science_keywords[1][term]).
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: science_keywords[0][variable_level_1]
description: Matches collections by science keyword subfield variable level 1. To specify multiple different science keywords use a different index for each science keyword (e.g. science_keywords[1][variable_level_1]).
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: science_keywords[0][variable_level_2]
description: Matches collections by science keyword subfield variable level 2. To specify multiple different science keywords use a different index for each science keyword (e.g. science_keywords[1][variable_level_2]).
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: science_keywords[0][variable_level_3]
description: Matches collections by science keyword subfield variable level 3. To specify multiple different science keywords use a different index for each science keyword (e.g. science_keywords[1][variable_level_3]).
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: science_keywords[0][detailed_variable]
description: Matches collections by science keyword subfield detailed variable. To specify multiple different science keywords use a different index for each science keyword (e.g. science_keywords[1][detailed_variable]).
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: spatial_keyword[]
description: Matches collections by spatial keyword.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: platform[]
description: Matches collections by platform short name.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: instrument[]
description: Matches collections by instrument short name.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: sensor[]
description: Matches collections by sensor short name.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: data_center[]
description: Matches collections by data center. Data centers include archive, processing, originating, and distribution centers.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: archive_center[]
description: Matches collections by archive center.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: project[]
description: Match collections by project short name.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: processing_level_id[]
description: Match collections by processing level ID.
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: attribute[]
description: '<p>Matches collections by additional attribute. An additional attribute name is accepted or a comma separated list of <code>type,name,min_value,max_value</code>.</p>
<p>Example: <code>int,HORIZONTALTILENUMBER,1,12</code></p>
<p>Type is the type of the additional attribute. It will find collections with additional attributes of that type and name with a value between min_value and max_value.</p>
<p>The default is for collections to match all the attribute parameters. This can be changed by specifying <code>or</code> option with <code>options[attribute][or]=true</code>.</p><p>For additional attribute range search, the default is inclusive on the range boundaries. This can be changed by specifying <code>exclude_boundary</code> option with <code>options[attribute][exclude_boundary]=true</code>.</p>'
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: temporal[]
description: "<p>The temporal datetime has to be in yyyy-MM-ddTHH:mm:ssZ format.</p>\n<p>The first two values of the parameter together define the temporal bounds.</p>\n<p>For temporal range search, the default is inclusive on the range boundaries.\nThis can be changed by specifying <code>exclude_boundary</code> option with <code>options[temporal][exclude_boundary]=true</code>.This option has no impact on periodic temporal searches.</p>\n<p>The collection's temporal range or the temporal range of the granules in the collection can be searched.\n <code>options[temporal][limit_to_granules]=true</code> will indicate that the temporal search should find collections based on the minimum and maximum values of each collection's granules' temporal range.\nIf a collection does not have any granules it will search the collection's temporal range.</p>"
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: updated_since
description: Find collections which have revision date starting at or after 'updated_since' param value
required: false
type: string
format: date-time
- in: query
name: revision_date
description: <p>Find collections based on either a single revision datetime, or a comma separated revision datetime range. If a single revision date is provided any collections with a revision date greater than or equal to the provided datetime are matched. If two dates are provided, it matches collections which have a revision date within the ranges of datetimes. The datetimes have to be in yyyy-MM-ddTHH:mm:ssZ format. The default is inclusive on the range boundaries.</p>
required: false
type: array
items:
type: string
format: date-time
collectionFormat: csv
- in: query
name: bounding_box
description: 'Matches collections with a spatial area intersecting the provided bounding box. Bounding boxes define an area on the earth aligned with longitude and latitude. The Bounding box parameters must be 4 comma-separated numbers: lower left longitude, lower left latitude, upper right longitude, upper right latitude.'
required: false
type: string
pattern: -?\d+,-?\d+,-?\d+,-?\d+
- in: query
name: polygon
description: 'Matches collections with a spatial area intersecting the provided polygon. Polygon points are provided in counter-clockwise order.
The last point should match the first point to close the polygon.
The values are listed comma separated in longitude latitude order, i.e. lon1, lat1, lon2, lat2, lon3, lat3, and so on.'
required: false
type: string
- in: query
name: point
description: Matches collections with a spatial area intersecting the given point. Search using a point involves using a pair of values representing the point coordinates as parameters. The first value is the longitude and second value is the latitude.
required: false
type: string
- in: query
name: line
description: 'Matches collections with a spatial area intersecting the given line. Lines are provided as a list of comma separated values representing coordinates of points along the line.
The coordinates are listed in the format lon1, lat1, lon2, lat2, lon3, lat3, and so on.'
required: false
type: string
- in: query
name: two_d_coordinate_system_name[]
description: Matches collections by a two dimensional coordinate system name (also referred to as a tiling identification system name).
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: browsable
description: Matches collections by whether or not the collection metadata includes at least one browse URL.
required: false
type: boolean
- in: query
name: downloadable
description: Matches collections by whether or not the collection metadata includes at least one download URL.
required: false
type: boolean
- in: query
name: has_granules
description: When <code>has_granules</code> is set to "true" or "false", results will be restricted to collections with or without granules, respectively.
required: false
type: boolean
- in: query
name: has_granules_or_cwic
description: When <code>has_granules_or_cwic</code> is set to "true" or "false", results will be restricted to collections with or without granules, respectively. Or they are CWIC tagged collections.
required: false
type: boolean
- in: query
name: collection_data_type[]
description: 'Matches collections by the collection data type. The following are aliases for "NEAR_REAL_TIME": "near_real_time", "nrt", "NRT", "near real time", "near-real time", "near-real-time", "near real-time".'
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: tag_key[]
description: '<p>Collections can be found by searching for associated tags. The following tag parameters are supported.</p>
<ul>
<li>tag_key</li>
<li>options: pattern</li>
<li>tag_originator_id</li>
<li>options: pattern</li>
<li>tag_data</li>
<li>options: pattern</li>
</ul>
<p><code>exclude</code> parameter can be used with tag_key to exclude any collections that are associated with the specified tag key from the search result.</p>'
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: include_tags
description: When true include tag information in the response for each of the matching collections.
required: false
type: boolean
- in: query
name: all_revisions
description: In addition to retrieving the latest revision for a collection parameter search, it is possible to return all revisions, including tombstone (deletion marker) revisons, by passing in <code>all_revisions=true</code> with the URL parameters. The reference and UMM JSON response formats are supported for all revision searches. References to tombstone revisions do not include the <code>location</code> tag and include an additional tag, <code>deleted</code>, which always has content of "true".
required: false
type: boolean
- in: query
name: include_granule_counts
description: When true include the number of matching granules for each matching collection.
required: false
type: boolean
- in: query
name: include_facets
description: When true include facet information in the legacy facet response format. When set to v2 include facet information in the updated version 2 facets format.
required: false
type: string
enum:
- 'true'
- 'false'
- v2
- in: query
name: hierarchical_facets
description: When include_facets is true and hierarchical_facets is true, return the legacy facet response with hierarchical fields for science keywords, platforms, instruments, data centers, and locations.
required: false
type: boolean
- in: query
name: include_highlights
description: When true highlight any of the terms provided in the keyword search that match within the collection summary. Only supported for the JSON response format.
required: false
type: boolean
- in: query
name: sort_key[]
description: "<p>Collection results are sorted by ascending entry title by default when a search does not result in a score. If a keyword search is performed then the search results will be sorted by relevance (score descending). One or more sort keys can be specified using the <code>sort_key[]</code> parameter. The order used impacts searching. Fields can be prepended with a <code>-</code> to sort in descending order. Ascending order is the default but <code>+</code> can be used to explicitly request ascending.</p>\n<h5>Valid Collection Sort Keys</h5>\n<ul>\n<li><code>entry_title</code></li>\n <li><code>dataset_id</code> - alias for entry_title</li>\n<li><code>short_name</code></li>\n<li><code>entry_id</code></li>\n<li><code>start_date</code></li>\n<li><code>end_date</code></li>\n <li><code>platform</code></li>\n<li><code>instrument</code></li>\n<li><code>sensor</code></li>\n<li><code>provider</code></li>\n<li><code>revision_date</code></li>\n<li><code>score</code> - document relevance score, defaults to descending.</li>\n<li><code>has_granules</code> - Sorts collections by whether they have granules or not. Collections with granules are sorted before collections without granules.</li>"
required: false
type: array
items:
type: string
collectionFormat: multi
- in: query
name: page_size
description: Number of results per page - default is 10, max is 2000.
required: false
type: integer
- in: query
name: page_num
description: The page number to return.
required: false
type: integer
- in: query
name: offset
description: As an alternative to page_num, a 0-based offset of individual results may be specified.
required: false
type: integer
- in: query
name: pretty
description: Return formatted results if set to true.
required: false
type: boolean
- in: query
name: token
description: Specifies a user/guest token from ECHO to use to authenticate yourself. This can also be specified as the header Echo-Token.
required: false
type: string
produces:
- application/echo10+xml
- application/json
- '*/*'
- application/vnd.nasa.cmr.umm_results+json
- application/metadata+xml
- application/iso19115+xml
- application/dif+xml
- application/vnd.google-earth.kml+xml
- application/xml
- application/opendata+json
- application/dif10+xml
- application/atom+xml
- text/csv
responses:
'200':
description: This will contain the collections that are found. The data produced is specific to the response format selected.
headers:
CMR-Took:
description: The time the query took in milliseconds to execute within the CMR.
type: integer
CMR-Hits:
description: The number of matches of the query.
type: integer
'400':
description: The query contained an invalid parameter. The response body contains details.
'500':
description: An internal server error occured. You should contact CMR operations for these errors.
default:
description: ''
headers:
CMR-Request-Id:
description: A unique identifier given to the request in the CMR.
type: string