Search requests

The search API allows you to execute a search query and get back search hits that match the query. The search API can be applied to a single dataset (see Simple search request) or across multiple datasets (see Multi-dataset search request).

Simple search request

POST /api/lms/search/v2/(dataset_id)
Form Parameters:
 
  • search – Search query to execute. Search query can be a combination of filters for any of dataset’s fields except for tms and view_id. There are different filters to apply: 1) match documents who’s field’s value is within the query’s range: {‘fieldName’: {‘from’: ‘val1’, ‘to’: ‘val2’}}; 2) match documents who’s field’s value is one of the query’s values: {‘fieldName’: [‘v0’, ‘v1’, ‘v2’]}; 3) match documents who’s field’s value matches the query exactly: {‘fieldName’: ‘value’}. Examples: 1) find all scenes acquired in 2016: ‘date’: {‘from’: ‘2016-01-01’, ‘to’: ‘2016-12-31’}; 2) find scenes acquired either on 1 August 2016, 1 September 2016, 1 October 2016: ‘date’: [‘2016-08-01’, ‘2016-09-01’, ‘2016-10-01’]; 3) find scenes acquired on 1 August 2016: ‘date’: ‘2016-08-01’
  • sort – (optional) Sorting to perform. Can either be in the form ‘fieldName’:’asc’ or ‘fieldName’:’desc’. Example: {‘cloudCover’: ‘asc’} (sort results such that the least cloudy scenes come first). Default: {‘date’: ‘desc’} (the newest scenes come first)
  • page – (optional) Number of page, used for pagination. Default: 1
  • limit – (optional) Number of results per page. Default: 500
  • fields – (optional) An array of the selective stored fields of the document to return for each hit, comma delimited. Not specifying any value will cause all fields to return. Example: [‘sceneId’, ‘cloudCover’]
Query Parameters:
 
  • api_key – (required) user’s API key

Example. Search for Landsat 8 scenes

Search for Landsat 8 scenes that are

  • acquired between 20 January 2015 and 31 December 2017: “date”: {“from”: “2015-01-25”,”to”: “2017-12-31”}
  • intersect with a point with geographic coordinates 36.42017738514984°N -120.57357788085938°W: “shape”:{“type”:”Point”,”coordinates”:[-120.57357788085938,36.42017738514984]}
  • hosted on AWS S3: “onAmazon”: true

Sort the results in such a way that the most recent scenes come first: “sort”: {“date”: “desc”}.

Return only scene identificator and cloud coverage percentage: “fields”: [“sceneID”,”cloudCoverage”].

Return 5 results per page: “limit”: 5.

Example request:

http

POST /api/lms/search/v2/landsat8?api_key=XXX HTTP/1.1
Host: gate.eos.com
Content-Type: application/json

{
    "search": {
        "date": {
            "from": "2015-01-25",
            "to": "2017-12-31"
        },
        "shape": {
            "type": "Point",
            "coordinates": [
                -120.57357788085938,
                36.42017738514984
            ]
        }
    },
    "onAmazon": true,
    "sort": {
        "date": "desc"
    },
    "page": 1,
    "limit": 5,
    "fields": [
        "sceneID",
        "cloudCoverage"
    ]
}

curl

curl -i -X POST 'https://gate.eos.com/api/lms/search/v2/landsat8?api_key=XXX' -H 'Content-Type: application/json' --data-raw '{"fields": ["sceneID", "cloudCoverage"], "limit": 5, "onAmazon": true, "page": 1, "search": {"date": {"from": "2015-01-25", "to": "2017-12-31"}, "shape": {"coordinates": [-120.57357788085938, 36.42017738514984], "type": "Point"}}, "sort": {"date": "desc"}}'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "meta": {
            "name": "satellite-meta-service",
            "page": 1,
            "found": 117,
            "limit": 8
    },
    "results": [{
            "sceneID": "LC80430352017350LGN00",
            "view_id": "L8/LC08_L1TP_043035_20171216_20171224_01_T1",
            "onAmazon": true,
            "storedInCollection": "01",
            "tms": "https://gate.eos.com/api/render/L8/LC08_L1TP_043035_20171216_20171224_01_T1/{band}/{z}/{x}/{y}",
            "productID": "LC08_L1TP_043035_20171216_20171224_01_T1",
            "cloudCoverage": 0.43
    }, {
            "sceneID": "LC80430352017334LGN00",
            "view_id": "L8/LC08_L1TP_043035_20171130_20171207_01_T1",
            "onAmazon": true,
            "storedInCollection": "01",
            "tms": "https://gate.eos.com/api/render/L8/LC08_L1TP_043035_20171130_20171207_01_T1/{band}/{z}/{x}/{y}",
            "productID": "LC08_L1TP_043035_20171130_20171207_01_T1",
            "cloudCoverage": 1.78
    }, {
            "sceneID": "LC80430352017318LGN00",
            "view_id": "L8/LC08_L1TP_043035_20171114_20171122_01_T1",
            "onAmazon": true,
            "storedInCollection": "01",
            "tms": "https://gate.eos.com/api/render/L8/LC08_L1TP_043035_20171114_20171122_01_T1/{band}/{z}/{x}/{y}",
            "productID": "LC08_L1TP_043035_20171114_20171122_01_T1",
            "cloudCoverage": 5.11
    }, {
            "sceneID": "LC80430352017302LGN00",
            "view_id": "L8/LC08_L1TP_043035_20171029_20171109_01_T1",
            "onAmazon": true,
            "storedInCollection": "01",
            "tms": "https://gate.eos.com/api/render/L8/LC08_L1TP_043035_20171029_20171109_01_T1/{band}/{z}/{x}/{y}",
            "productID": "LC08_L1TP_043035_20171029_20171109_01_T1",
            "cloudCoverage": 73.69
    }, {
            "sceneID": "LC80430352017286LGN00",
            "view_id": "L8/LC08_L1TP_043035_20171013_20171024_01_T1",
            "onAmazon": true,
            "storedInCollection": "01",
            "tms": "https://gate.eos.com/api/render/L8/LC08_L1TP_043035_20171013_20171024_01_T1/{band}/{z}/{x}/{y}",
            "productID": "LC08_L1TP_043035_20171013_20171024_01_T1",
            "cloudCoverage": 0.04
    }, {
            "sceneID": "LC80430352017270LGN00",
            "view_id": "L8/LC08_L1TP_043035_20170927_20171013_01_T1",
            "onAmazon": true,
            "storedInCollection": "01",
            "tms": "https://gate.eos.com/api/render/L8/LC08_L1TP_043035_20170927_20171013_01_T1/{band}/{z}/{x}/{y}",
            "productID": "LC08_L1TP_043035_20170927_20171013_01_T1",
            "cloudCoverage": 0.01
    }, {
            "sceneID": "LC80430352017254LGN00",
            "view_id": "L8/LC08_L1TP_043035_20170911_20170927_01_T1",
            "onAmazon": true,
            "storedInCollection": "01",
            "tms": "https://gate.eos.com/api/render/L8/LC08_L1TP_043035_20170911_20170927_01_T1/{band}/{z}/{x}/{y}",
            "productID": "LC08_L1TP_043035_20170911_20170927_01_T1",
            "cloudCoverage": 21.97
    }, {
            "sceneID": "LC80430352017238LGN00",
            "view_id": "L8/LC08_L1TP_043035_20170826_20170913_01_T1",
            "onAmazon": true,
            "storedInCollection": "01",
            "tms": "https://gate.eos.com/api/render/L8/LC08_L1TP_043035_20170826_20170913_01_T1/{band}/{z}/{x}/{y}",
            "productID": "LC08_L1TP_043035_20170826_20170913_01_T1",
            "cloudCoverage": 25.09
    }]
}

Multi-dataset search request

Search API for multiple datasets. Datasets are listed under required search.satellites field instead of URL.

Another significant difference from the Simple search request is that search filter is ignored for the dataset if the field is not present in the mapping for said dataset.

POST /api/lms/search/v2
Form Parameters:
 
  • search – Search query to execute. Nested field “satellites” is required. Search query can be a combination of filters for any of dataset’s fields except for tms and view_id. There are different filters to apply: 1) match documents who’s field’s value is within the query’s range: {‘fieldName’: {‘from’: ‘val1’, ‘to’: ‘val2’}}; 2) match documents who’s field’s value is one of the query’s values: {‘fieldName’: [‘v0’, ‘v1’, ‘v2’]}; 3) match documents who’s field’s value matches the query exactly: {‘fieldName’: ‘value’}. Examples: 1) find all scenes acquired in 2016: ‘date’: {‘from’: ‘2016-01-01’, ‘to’: ‘2016-12-31’}; 2) find scenes acquired either on 1 August 2016, 1 September 2016, 1 October 2016: ‘date’: [‘2016-08-01’, ‘2016-09-01’, ‘2016-10-01’]; 3) find scenes acquired on 1 August 2016: ‘date’: ‘2016-08-01’
  • sort – (optional) Sorting to perform. Can either be in the form ‘fieldName’:’asc’ or ‘fieldName’:’desc’. Example: {‘cloudCover’: ‘asc’} (sort results such that the least cloudy scenes come first). Default: {‘date’: ‘desc’} (the newest scenes come first)
  • page – (optional) Number of page, used for pagination. Default: 1
  • limit – (optional) Number of results per page. Default: 500
  • fields – (optional) An array of the selective stored fields of the document to return for each hit, comma delimited. Not specifying any value will cause all fields to return. Example: [‘sceneId’, ‘cloudCover’]
Query Parameters:
 
  • api_key – (required) user’s API key

Example request:

http

POST /api/lms/search/v2?api_key=%7CAPI_KEY%7C HTTP/1.1
Host: gate.eos.com
Content-Type: application/json

{
    "search": {
        "satellites": ["landsat8", "sentinel2"],
        "date": {
            "from": "2018-08-20"
        },
        "cloudCoverage": {
            "from": 0,
            "to": 100
        },
        "sunElevation": {
            "from": 0,
            "to": 90
        },
        "shape": {
            "type": "Point",
            "coordinates": [-118.23486328125001, 33.99575015925125]
        },
        "dayOrNight": "day",
        "onAmazon": true
    },
    "limit": 5,
    "fields": ["sunElevation", "cloudCoverage", "sceneID", "date", "path", "storedInCollection", "productID", "sensor", "row", "dataCoveragePercentage"]
}

curl

curl -i -X POST 'https://gate.eos.com/api/lms/search/v2?api_key=%7CAPI_KEY%7C' -H 'Content-Type: application/json' --data-raw '{"fields": ["sunElevation", "cloudCoverage", "sceneID", "date", "path", "storedInCollection", "productID", "sensor", "row", "dataCoveragePercentage"], "limit": 5, "search": {"cloudCoverage": {"from": 0, "to": 100}, "date": {"from": "2018-08-20"}, "dayOrNight": "day", "onAmazon": true, "satellites": ["landsat8", "sentinel2"], "shape": {"coordinates": [-118.23486328125001, 33.99575015925125], "type": "Point"}, "sunElevation": {"from": 0, "to": 90}}}'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
            "cloudCoverage": 23.1,
            "view_id": "S2/11/S/LT/2018/11/15/0",
            "dataCoveragePercentage": 100.0,
            "tms": "https://gate.eos.com/api/render/S2/11/S/LT/2018/11/15/0/{band}/{z}/{x}/{y}",
            "sceneID": "S2A_tile_20181115_11SLT_0",
            "sunElevation": 36.0003817244383,
            "date": "2018-11-15",
            "satellite": "sentinel2"
    }, {
            "cloudCoverage": 5.73,
            "view_id": "S2/11/S/LT/2018/11/10/0",
            "dataCoveragePercentage": 100.0,
            "tms": "https://gate.eos.com/api/render/S2/11/S/LT/2018/11/10/0/{band}/{z}/{x}/{y}",
            "sceneID": "S2B_tile_20181110_11SLT_0",
            "sunElevation": 37.3327730689946,
            "date": "2018-11-10",
            "satellite": "sentinel2"
    }, {
            "cloudCoverage": 7.09,
            "view_id": "S2/11/S/LT/2018/11/5/0",
            "dataCoveragePercentage": 100.0,
            "tms": "https://gate.eos.com/api/render/S2/11/S/LT/2018/11/5/0/{band}/{z}/{x}/{y}",
            "sceneID": "S2A_tile_20181105_11SLT_0",
            "sunElevation": 38.7597633079668,
            "date": "2018-11-05",
            "satellite": "sentinel2"
    }, {
            "cloudCoverage": 0.1,
            "productID": "LC08_L1TP_041036_20181103_20181115_01_T1",
            "sunElevation": 37.5803368,
            "sceneID": "LC80410362018307LGN00",
            "storedInCollection": "01",
            "row": 36.0,
            "view_id": "L8/LC08_L1TP_041036_20181103_20181115_01_T1",
            "sensor": "OLI_TIRS",
            "path": 41.0,
            "onGoogle": false,
            "onAmazon": true,
            "satellite": "landsat8",
            "date": "2018-11-03",
            "tms": "https://gate.eos.com/api/render/L8/LC08_L1TP_041036_20181103_20181115_01_T1/{band}/{z}/{x}/{y}"
    }, {
            "cloudCoverage": 0.16,
            "view_id": "S2/11/S/LT/2018/10/31/0",
            "dataCoveragePercentage": 100.0,
            "tms": "https://gate.eos.com/api/render/S2/11/S/LT/2018/10/31/0/{band}/{z}/{x}/{y}",
            "sceneID": "S2B_tile_20181031_11SLT_0",
            "sunElevation": 40.2741134030004,
            "date": "2018-10-31",
            "satellite": "sentinel2"
    }],
    "meta": {
            "name": "satellite-meta-service",
            "page": 1,
            "limit": 5,
            "found": 25
    }
}