Searching ScienceBase with ScienceBasePy.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# Searching ScienceBase with sciencebasepy\n",
    "## Open a sciencebasepy session\n",
    "First, you need to create an SbSession object with which to search. We will be searching public items, so login is not required."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from sciencebasepy import SbSession\n",
    "sb = SbSession()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic Searches\n",
    "### Keyword Search\n",
    "Search for ScienceBase Catalog Items containing the word \"water\" using the key word `q` search."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 726489 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 136.56088},\n",
       "   'hasChildren': False,\n",
       "   'id': '5053769be4b097cd4fcdd30f',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/5053769be4b097cd4fcdd30f'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=5053769be4b097cd4fcdd30f'}},\n",
       "   'title': 'Water markets and water quality'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=water&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=water&max=1'},\n",
       " 'took': '1.4s',\n",
       " 'total': 726489}"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = sb.find_items({'q':'water', 'max':1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Related Item Searches\n",
    "### Find an Item's Children\n",
    "Find all children of the item specified by the given ID, including linked parent IDs, using the `parentId` parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 215 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': False,\n",
       "   'id': '4f4e4774e4b07f02db47e251',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/4f4e4774e4b07f02db47e251'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=4f4e4774e4b07f02db47e251'}},\n",
       "   'summary': 'ScienceBase Global context providing access to all items ScienceBase provides a data cataloging and collaborative data management platform for USGS scientists and partners. ScienceBase provides a central search and discovery application along with Web services that facilitate other applications. Research communities can set up their own virtual spaces that contain items of particular import to their work. Items are added to the ScienceBase Catalog through one of several methods:         Harvesting engines access other catalogs or more simple listings of data resources and integrate them into ScienceBase by analyzing core elements needed for query and contextualization.         Authorized users enter new items by uploading single or [...]',\n",
       "   'title': 'Global'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?max=1&parentId=4f4e4760e4b07f02db47df9c&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?max=1&parentId=4f4e4760e4b07f02db47df9c'},\n",
       " 'took': '4ms',\n",
       " 'total': 215}"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "base_item_id = \"4f4e4760e4b07f02db47df9c\"\n",
    "response = sb.find_items({'parentId': base_item_id, 'max': 1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Find all descendants of an item\n",
    "Find all the descentants of an item using the `ancestors` parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 9156531 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': True,\n",
       "   'id': '59945cd0e4b0fe2b9fe91379',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/59945cd0e4b0fe2b9fe91379'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=59945cd0e4b0fe2b9fe91379'}},\n",
       "   'summary': 'External projects funded by the Peninsular Florida LCC.',\n",
       "   'title': 'Projects'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?max=1&filter=ancestors%3D4f4e4760e4b07f02db47df9c&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?max=1&filter=ancestors%3D4f4e4760e4b07f02db47df9c'},\n",
       " 'took': '857ms',\n",
       " 'total': 9156531}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = sb.find_items({'ancestors': base_item_id, 'max':1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Filters\n",
    "Perform a filter search by adding the parameter `filter=`. `should` instead of `filter` performs an \"OR\" search. **Note:** When using multiple filters in a search, you have to number them. There are 10 filters available, `filter0` through `filter9`. If you just use `filter` multiple times in the dictionary, you will only be left with the last one, as python will overwrite the value in the dictionary.\n",
    "\n",
    "### browseType\n",
    "Find items by ScienceBase browse type.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 2206 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': False,\n",
       "   'id': '561809a4e4b0cdb063e3fd56',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/561809a4e4b0cdb063e3fd56'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=561809a4e4b0cdb063e3fd56'}},\n",
       "   'summary': 'Estimates of county tile drainage in the Mississippi River Basin. Data Sources: 2012 USDA NASS Census of Agriculture; World Resources Institute. 2008. Assessing Farm Drainage; USGS Northern Prairie Wildlife Research Center. 2014. Assessment of agricultural subsoil pattern tile drainage on wetland hydrology and ecosystem services in the Prairie Pothole Region.      Field Description   tiled_acre Acres drained by tile (NASS Census of Agriculture, 2012) or drainage permit acres in Dakotas (NPWRC, 2014), whichever is higher.   pct_tile Percent of county drained by tile (tiled_acre/cty_acr*100)   prmtac2 Acres under drainage permit in North or South Dakota (NPWRC, 2014).   Best_Guess Acres drained by tile (WRI - Assessing Farm Drainage, [...]',\n",
       "   'title': 'County Tile Drainage - Mississippi River Basin'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=browseType%3DArcGIS+Service+Definition&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=browseType%3DArcGIS+Service+Definition&max=1'},\n",
       " 'took': '3ms',\n",
       " 'total': 2206}"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = sb.find_items({'filter': 'browseType=ArcGIS Service Definition', 'max': 1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### browseCategory\n",
    "Find items by ScienceBase browse category."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 42563 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': False,\n",
       "   'id': '561809a4e4b0cdb063e3fd56',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/561809a4e4b0cdb063e3fd56'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=561809a4e4b0cdb063e3fd56'}},\n",
       "   'summary': 'Estimates of county tile drainage in the Mississippi River Basin. Data Sources: 2012 USDA NASS Census of Agriculture; World Resources Institute. 2008. Assessing Farm Drainage; USGS Northern Prairie Wildlife Research Center. 2014. Assessment of agricultural subsoil pattern tile drainage on wetland hydrology and ecosystem services in the Prairie Pothole Region.      Field Description   tiled_acre Acres drained by tile (NASS Census of Agriculture, 2012) or drainage permit acres in Dakotas (NPWRC, 2014), whichever is higher.   pct_tile Percent of county drained by tile (tiled_acre/cty_acr*100)   prmtac2 Acres under drainage permit in North or South Dakota (NPWRC, 2014).   Best_Guess Acres drained by tile (WRI - Assessing Farm Drainage, [...]',\n",
       "   'title': 'County Tile Drainage - Mississippi River Basin'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=browseCategory%3DData&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=browseCategory%3DData&max=1'},\n",
       " 'took': '13ms',\n",
       " 'total': 42563}"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = sb.find_items({'filter': 'browseCategory=Data', 'max': 1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### party"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 214 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'contacts': [{'active': True,\n",
       "     'contactType': 'person',\n",
       "     'email': 'ipearse@usgs.gov',\n",
       "     'firstName': 'Ian',\n",
       "     'jobTitle': 'Research Ecologist',\n",
       "     'lastName': 'Pearse',\n",
       "     'middleName': 'S',\n",
       "     'name': 'Ian S Pearse',\n",
       "     'oldPartyId': 72543,\n",
       "     'organization': {'displayText': 'Fort Collins Science Center'},\n",
       "     'primaryLocation': {'building': 'NRRC Bldg C',\n",
       "      'buildingCode': 'KBA',\n",
       "      'faxPhone': '9702269230',\n",
       "      'mailAddress': {},\n",
       "      'name': 'CN=Ian S Pearse,OU=Fort Collins,OU=Users,OU=FortCollinsCO-B,OU=CR,DC=gs,DC=doi,DC=net - Primary Location',\n",
       "      'officePhone': '9702269145',\n",
       "      'streetAddress': {'city': 'Fort Collins',\n",
       "       'country': 'US',\n",
       "       'line1': '2150 Centre Avenue Bldg C',\n",
       "       'state': 'CO',\n",
       "       'zip': '80526'}},\n",
       "     'type': 'Point of Contact'},\n",
       "    {'active': True,\n",
       "     'contactType': 'person',\n",
       "     'email': 'ipearse@usgs.gov',\n",
       "     'firstName': 'Ian',\n",
       "     'jobTitle': 'Research Ecologist',\n",
       "     'lastName': 'Pearse',\n",
       "     'middleName': 'S',\n",
       "     'name': 'Ian S Pearse',\n",
       "     'oldPartyId': 72543,\n",
       "     'organization': {'displayText': 'Fort Collins Science Center'},\n",
       "     'primaryLocation': {'building': 'NRRC Bldg C',\n",
       "      'buildingCode': 'KBA',\n",
       "      'faxPhone': '9702269230',\n",
       "      'mailAddress': {},\n",
       "      'name': 'CN=Ian S Pearse,OU=Fort Collins,OU=Users,OU=FortCollinsCO-B,OU=CR,DC=gs,DC=doi,DC=net - Primary Location',\n",
       "      'officePhone': '9702269145',\n",
       "      'streetAddress': {'city': 'Fort Collins',\n",
       "       'country': 'US',\n",
       "       'line1': '2150 Centre Avenue Bldg C',\n",
       "       'state': 'CO',\n",
       "       'zip': '80526'}},\n",
       "     'type': 'Originator'},\n",
       "    {'name': 'Ryan Paul',\n",
       "     'primaryLocation': {'mailAddress': {}, 'streetAddress': {}},\n",
       "     'type': 'Originator'},\n",
       "    {'name': 'Paul J Ode',\n",
       "     'primaryLocation': {'mailAddress': {}, 'streetAddress': {}},\n",
       "     'type': 'Originator'},\n",
       "    {'active': True,\n",
       "     'contactType': 'person',\n",
       "     'email': 'ipearse@usgs.gov',\n",
       "     'firstName': 'Ian',\n",
       "     'jobTitle': 'Research Ecologist',\n",
       "     'lastName': 'Pearse',\n",
       "     'middleName': 'S',\n",
       "     'name': 'Ian S Pearse',\n",
       "     'oldPartyId': 72543,\n",
       "     'organization': {'displayText': 'Fort Collins Science Center'},\n",
       "     'primaryLocation': {'building': 'NRRC Bldg C',\n",
       "      'buildingCode': 'KBA',\n",
       "      'faxPhone': '9702269230',\n",
       "      'mailAddress': {},\n",
       "      'name': 'CN=Ian S Pearse,OU=Fort Collins,OU=Users,OU=FortCollinsCO-B,OU=CR,DC=gs,DC=doi,DC=net - Primary Location',\n",
       "      'officePhone': '9702269145',\n",
       "      'streetAddress': {'city': 'Fort Collins',\n",
       "       'country': 'US',\n",
       "       'line1': '2150 Centre Avenue Bldg C',\n",
       "       'state': 'CO',\n",
       "       'zip': '80526'}},\n",
       "     'type': 'Metadata Contact'},\n",
       "    {'contactType': 'organization',\n",
       "     'email': 'sciencebase@usgs.gov',\n",
       "     'name': 'U.S. Geological Survey - ScienceBase',\n",
       "     'oldPartyId': 70157,\n",
       "     'onlineResource': 'https://www.sciencebase.gov',\n",
       "     'primaryLocation': {'mailAddress': {'city': 'Denver',\n",
       "       'country': 'United States',\n",
       "       'line1': 'Denver Federal Center',\n",
       "       'line2': 'Building 810',\n",
       "       'mailStopCode': '302',\n",
       "       'state': 'CO',\n",
       "       'zip': '80225'},\n",
       "      'name': 'U.S. Geological Survey - ScienceBase - Location',\n",
       "      'officePhone': '18882758747',\n",
       "      'streetAddress': {}},\n",
       "     'type': 'Distributor'},\n",
       "    {'active': True,\n",
       "     'contactType': 'organization',\n",
       "     'name': 'Fort Collins Science Center',\n",
       "     'oldPartyId': 17368,\n",
       "     'primaryLocation': {'mailAddress': {},\n",
       "      'name': 'Fort Collins Science Center - NRRC BLDG C [KBA]',\n",
       "      'streetAddress': {}},\n",
       "     'type': 'SDC Data Owner'},\n",
       "    {'contactType': 'organization',\n",
       "     'name': 'Ecosystems',\n",
       "     'organization': {'directoryId': '17044', 'displayText': 'Ecosystems'},\n",
       "     'primaryLocation': {'mailAddress': {}, 'streetAddress': {}},\n",
       "     'type': 'USGS Mission Area'}],\n",
       "   'id': '5bb67c9be4b0fc368e894684',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/5bb67c9be4b0fc368e894684'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=5bb67c9be4b0fc368e894684'}}}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=party%3D%7Bname%3AFort+Collins+Science+Center%7D&max=1&fields=contacts&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=party%3D%7Bname%3AFort+Collins+Science+Center%7D&max=1&fields=contacts'},\n",
       " 'took': '29ms',\n",
       " 'total': 214}"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = sb.find_items({'filter':'party={name:Fort Collins Science Center}','fields':'contacts', 'max': 1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### partyWithName\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 197 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': False,\n",
       "   'id': '5bb67c9be4b0fc368e894684',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/5bb67c9be4b0fc368e894684'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=5bb67c9be4b0fc368e894684'}},\n",
       "   'summary': 'A dataset of caterpillar performance in an experiment manipulating mean and variance of xanthotoxin levels in diet. Caterpillar growth, development time, and egg production of mated females is presented. Data were collected by all authors in 2017 in a laboratory at Colorado State University, Fort Collins, CO.',\n",
       "   'title': 'Laboratory Data on Cabbage Looper Moth Response to Xanthotoxin, 2018'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=partyWithName%3D17368_Fort+Collins+Science+Center&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=partyWithName%3D17368_Fort+Collins+Science+Center&max=1'},\n",
       " 'took': '19ms',\n",
       " 'total': 197}"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = sb.find_items({'filter': 'partyWithName=17368_Fort Collins Science Center', 'max': 1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### itemIdentifier\n",
    "{“type”: <type>,\"scheme:<scheme>,“key”: <key>}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 3699 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': False,\n",
       "   'id': '5bb67c9be4b0fc368e894684',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/5bb67c9be4b0fc368e894684'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=5bb67c9be4b0fc368e894684'}},\n",
       "   'summary': 'A dataset of caterpillar performance in an experiment manipulating mean and variance of xanthotoxin levels in diet. Caterpillar growth, development time, and egg production of mated females is presented. Data were collected by all authors in 2017 in a laboratory at Colorado State University, Fort Collins, CO.',\n",
       "   'title': 'Laboratory Data on Cabbage Looper Moth Response to Xanthotoxin, 2018'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=itemIdentifier%3D%7B%22type%22%3A+%22DOI%22%2C%22scheme%22%3A+%22https%3A%2F%2Fwww.sciencebase.gov%2Fvocab%2Fcategory%2Fitem%2Fidentifier%22%7D&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=itemIdentifier%3D%7B%22type%22%3A+%22DOI%22%2C%22scheme%22%3A+%22https%3A%2F%2Fwww.sciencebase.gov%2Fvocab%2Fcategory%2Fitem%2Fidentifier%22%7D&max=1'},\n",
       " 'took': '860ms',\n",
       " 'total': 3699}"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = sb.find_items({'filter': 'itemIdentifier={\"type\": \"DOI\",\"scheme\": \"https://www.sciencebase.gov/vocab/category/item/identifier\"}', 'max': 1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### facets"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 8777 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': False,\n",
       "   'id': '55e385b5e4b05561fa20825e',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/55e385b5e4b05561fa20825e'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=55e385b5e4b05561fa20825e'}},\n",
       "   'summary': 'Value for wetland breeding birds based on herbaceous wetland breeding bird abundances and habitat models.',\n",
       "   'title': 'UMRGLR JV - Wetland Breeding Bird Habitat Priorities'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=facets.facetName%3DShapefile&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=facets.facetName%3DShapefile&max=1'},\n",
       " 'took': '27ms',\n",
       " 'total': 8777}"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = sb.find_items({'filter': 'facets.facetName=Shapefile', 'max': 1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### dateRange\n",
    "format is `dateRange={“start”: ?, “end”: ?, “dateType”: ?, “choice”: ?}`\n",
    "\n",
    "\n",
    "dateRange={“dateType”:\"End\", \"choice\":\"year\"}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 25984 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': False,\n",
       "   'id': '5cbacd38e4b0c3b00662574e',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/5cbacd38e4b0c3b00662574e'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=5cbacd38e4b0c3b00662574e'}},\n",
       "   'summary': 'Layered geospatial PDF 7.5 Minute Quadrangle Map. Layers of geospatial data include orthoimagery, roads, grids, geographic names, elevation contours, hydrography, and other selected map features. This map is derived from GIS (geospatial information system) data. It represents a repackaging of GIS data in traditional map form, not creation of new information. The geospatial data in this map are from selected National Map data holdings and other government sources.',\n",
       "   'title': 'USGS US Topo 7.5-minute map for Cayce, KY,TN 2019'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=dateRange%3D%7B%22start%22%3A%222019-03-04%22%2C%22end%22%3A%222020-03-04%22%2C%22dateType%22%3A%22End%22%2C%22choice%22%3A%22range%22%7D&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=dateRange%3D%7B%22start%22%3A%222019-03-04%22%2C%22end%22%3A%222020-03-04%22%2C%22dateType%22%3A%22End%22%2C%22choice%22%3A%22range%22%7D&max=1'},\n",
       " 'took': '106ms',\n",
       " 'total': 25984}"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = sb.find_items({'filter': 'dateRange={\"start\":\"2019-03-04\",\"end\":\"2020-03-04\",\"dateType\":\"End\",\"choice\":\"range\"}','max':1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 5 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': True,\n",
       "   'id': '5d94b80fe4b0c4f70d0e3033',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/5d94b80fe4b0c4f70d0e3033'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=5d94b80fe4b0c4f70d0e3033'}},\n",
       "   'summary': 'A collection of approximately 100,000 handwritten and typewritten scout tickets from Oklahoma sorted by section-township-range, as well as a small percentage of scout tickets from nearby states.',\n",
       "   'title': 'Oklahoma Scout Tickets'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=dateRange%3D%7B%22dateType%22%3A%22creation%22%2C%22choice%22%3A%22month%22%7D&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=dateRange%3D%7B%22dateType%22%3A%22creation%22%2C%22choice%22%3A%22month%22%7D&max=1'},\n",
       " 'took': '273ms',\n",
       " 'total': 5}"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Find all items created in the past month\n",
    "response = sb.find_items({'filter': 'dateRange={\"dateType\":\"creation\",\"choice\":\"month\"}', 'max': 1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### tags\n",
    "Simple tag name search `filter=tags=water`\n",
    "Format is `tags={\"name\":name,\"type\":type,\"scheme\":scheme}`\n",
    "\n",
    "tags=water"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 1053 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': False,\n",
       "   'id': '57348adfe4b0dae0d5de6159',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/57348adfe4b0dae0d5de6159'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=57348adfe4b0dae0d5de6159'}},\n",
       "   'summary': 'This EnviroAtlas web service supports research and online mapping activities related to EnviroAtlas (https://www.epa.gov/enviroatlas). The Clean and Plentiful Water category in this web service includes layers illustrating the ecosystems and natural resources that filter and regulate water, the need or demand for clean and plentiful water, the impacts associated with water quality, and factors that place stress on water quality and supply. EnviroAtlas allows the user to interact with a web-based, easy-to-use, mapping application to view and analyze multiple ecosystem services for the conterminous United States. Additional descriptive information about each attribute in this web service is located within each web service layer (see [...]',\n",
       "   'title': 'EnviroAtlas - Clean and Plentiful Water Metrics for the Conterminous United States'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=tags%3D%7B%22name%22%3A%22water%22%7D&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=tags%3D%7B%22name%22%3A%22water%22%7D&max=1'},\n",
       " 'took': '4ms',\n",
       " 'total': 1053}"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = sb.find_items({'filter': 'tags={\"name\":\"water\"}', 'max': 1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### spatialQuery\n",
    "Search via geoJSON"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 119642 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': False,\n",
       "   'id': '5c085d3de4b0815414d08501',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/5c085d3de4b0815414d08501'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=5c085d3de4b0815414d08501'}},\n",
       "   'summary': 'This is the Original Product Resolution (OPR) Digital Elevation Model (DEM) as provided to the USGS. This DEM is delivered in the original resolution, with the original spatial reference. These data may be used as the source of updates to the seamless layers of the 3D Elevation Program, which serves as the elevation layer of the National Map. These data can be used by scientists and resource managers for global change research, hydrologic modeling, resource monitoring, mapping and visualization, and many other applications.',\n",
       "   'title': 'USGS NED Original Product Resolution NE Sandhills B4 UTM14 2016 dem 14T KM 6530 IMG 2018'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=spatialQuery%3D%7Btype%3A%22envelope%22%2Ccoordinates%3A%5B%5B-104.7756918907963%2C42.49482654800248%5D%2C+%5B-99.85381689079756%2C40.11845545879961%5D%5D%7D&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=spatialQuery%3D%7Btype%3A%22envelope%22%2Ccoordinates%3A%5B%5B-104.7756918907963%2C42.49482654800248%5D%2C+%5B-99.85381689079756%2C40.11845545879961%5D%5D%7D&max=1'},\n",
       " 'took': '4.1s',\n",
       " 'total': 119642}"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = sb.find_items({\n",
    "    'filter': 'spatialQuery={type:\"envelope\",coordinates:[[-104.7756918907963,42.49482654800248], [-99.85381689079756,40.11845545879961]]}',\n",
    "    'max': 1\n",
    "})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### extentQuery\n",
    "Find items whose footprint intersects Colorado (extent 36) with a buffer of .125 degrees."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 173221 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': False,\n",
       "   'id': '57348adfe4b0dae0d5de6159',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/57348adfe4b0dae0d5de6159'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=57348adfe4b0dae0d5de6159'}},\n",
       "   'summary': 'This EnviroAtlas web service supports research and online mapping activities related to EnviroAtlas (https://www.epa.gov/enviroatlas). The Clean and Plentiful Water category in this web service includes layers illustrating the ecosystems and natural resources that filter and regulate water, the need or demand for clean and plentiful water, the impacts associated with water quality, and factors that place stress on water quality and supply. EnviroAtlas allows the user to interact with a web-based, easy-to-use, mapping application to view and analyze multiple ecosystem services for the conterminous United States. Additional descriptive information about each attribute in this web service is located within each web service layer (see [...]',\n",
       "   'title': 'EnviroAtlas - Clean and Plentiful Water Metrics for the Conterminous United States'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=extentQuery%3D%7B%22extent%22%3A36%2C%22relation%22%3A%22intersects%22%2C%22buffer%22%3A%22.125%22%7D&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=extentQuery%3D%7B%22extent%22%3A36%2C%22relation%22%3A%22intersects%22%2C%22buffer%22%3A%22.125%22%7D&max=1'},\n",
       " 'took': '3.7s',\n",
       " 'total': 173221}"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = sb.find_items({'filter': 'extentQuery={\"extent\":36,\"relation\":\"intersects\",\"buffer\":\".125\"}','max': 1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Filter Conjunction\n",
    "Find items tagged with either \"water\" or \"birds\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 4901 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': False,\n",
       "   'id': '57348adfe4b0dae0d5de6159',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/57348adfe4b0dae0d5de6159'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=57348adfe4b0dae0d5de6159'}},\n",
       "   'summary': 'This EnviroAtlas web service supports research and online mapping activities related to EnviroAtlas (https://www.epa.gov/enviroatlas). The Clean and Plentiful Water category in this web service includes layers illustrating the ecosystems and natural resources that filter and regulate water, the need or demand for clean and plentiful water, the impacts associated with water quality, and factors that place stress on water quality and supply. EnviroAtlas allows the user to interact with a web-based, easy-to-use, mapping application to view and analyze multiple ecosystem services for the conterminous United States. Additional descriptive information about each attribute in this web service is located within each web service layer (see [...]',\n",
       "   'title': 'EnviroAtlas - Clean and Plentiful Water Metrics for the Conterminous United States'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=tags%3Dwater&filter=tags%3Dbirds&conjunction=tags%3DOR&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?filter=tags%3Dwater&filter=tags%3Dbirds&conjunction=tags%3DOR&max=1'},\n",
       " 'took': '6ms',\n",
       " 'total': 4901}"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = sb.find_items({\n",
    "    'filter': ['tags=water','tags=birds'],\n",
    "    'conjunction': 'tags=OR',\n",
    "    'max': 1})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 4901 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': False,\n",
       "   'id': '57348adfe4b0dae0d5de6159',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/57348adfe4b0dae0d5de6159'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=57348adfe4b0dae0d5de6159'}},\n",
       "   'summary': 'This EnviroAtlas web service supports research and online mapping activities related to EnviroAtlas (https://www.epa.gov/enviroatlas). The Clean and Plentiful Water category in this web service includes layers illustrating the ecosystems and natural resources that filter and regulate water, the need or demand for clean and plentiful water, the impacts associated with water quality, and factors that place stress on water quality and supply. EnviroAtlas allows the user to interact with a web-based, easy-to-use, mapping application to view and analyze multiple ecosystem services for the conterminous United States. Additional descriptive information about each attribute in this web service is located within each web service layer (see [...]',\n",
       "   'title': 'EnviroAtlas - Clean and Plentiful Water Metrics for the Conterminous United States'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?max=1&should=tags%3Dwater&should=tags%3Dbirds&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?max=1&should=tags%3Dwater&should=tags%3Dbirds'},\n",
       " 'took': '5ms',\n",
       " 'total': 4901}"
      ]
     },
     "execution_count": 33,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Can also accomplish the same thing using 'should' instead of 'filter'\n",
    "response = sb.find_items({\n",
    "    'should': ['tags=water','tags=birds'],\n",
    "    'max': 1\n",
    "})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Lucene Query\n",
    "lucene query on the Item JSON model using `lq` parameter. Requires the `q` parameter to be specified as well, use '' if you don't want results restricted."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 49407 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 11.2394285},\n",
       "   'hasChildren': False,\n",
       "   'id': '5d87b193e4b0c4f70d08fe9e',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/5d87b193e4b0c4f70d08fe9e'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=5d87b193e4b0c4f70d08fe9e'}},\n",
       "   'summary': 'Core Research Center, core B851, from well operated by WEXPRO COMPANYRaw Properties from download, web scrape, MapServer, and Macrostrat API{\"Lib Num\": \"B851\", \"API Num\": \"4903520589\", \"Operator\": \"WEXPRO COMPANY\", \"Well Name\": \"1 MESA UNIT\", \"Field\": \"PINEDALE\", \"State\": \"WY\", \"County\": \"SUBLETTE\", \"Type\": \"SLABBED\", \"Photos\": \"T\", \"Thin Sec\": \"T\", \"Analysis\": \"T\", \"Latitude\": \"42.76659\", \"Longitude\": \"-109.87159\", \"coordinates_geohash\": \"9x9g7c3vqqhw\", \"Source\": \"FROM STATE RECORDS\", \"Security Flag\": \"NO SPECIAL RESTRICTIONS\", \"crc_collection_name\": \"core\", \"sb_parent_id\": \"4f4e49dae4b07f02db5e0486\", \"intervals\": [{\"Formation\": \"LANCE\", \"Age\": \"CRET\", \"Min Depth\": \"8688\", \"Max Depth\": \"8769\"}, {\"Formation\": \"LANCE\", \"Age\": \"CRET\", [...]',\n",
       "   'title': 'Core Research Center Core B851'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=&lq=%28tags.name%28%2Bbirds%29+AND+tags.name%28%2Bwater%29%29+OR+tags.name%28%2BWY%29&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=&lq=%28tags.name%28%2Bbirds%29+AND+tags.name%28%2Bwater%29%29+OR+tags.name%28%2BWY%29&max=1'},\n",
       " 'took': '1s',\n",
       " 'total': 49407}"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Find items that are tagged with \"birds\" AND \"water, OR are tagged with \"WY\"\n",
    "response = sb.find_items({\n",
    "    'q': '',\n",
    "    'lq': '(tags.name(+birds) AND tags.name(+water)) OR tags.name(+WY)',\n",
    "    'max': 1\n",
    "})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 1 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 33.11775},\n",
       "   'hasChildren': True,\n",
       "   'id': '5474ec49e4b04d7459a7eab2',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/5474ec49e4b04d7459a7eab2'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=5474ec49e4b04d7459a7eab2'}},\n",
       "   'summary': 'These resources are a collection of formally released datasets and data products created or managed by the U.S. Geological Survey. The collection provides access to data and services to facilitate public data sharing, as well as to help establish linkages to associated publications and projects both within and outside of the bureau.  For more information about the process of completing a USGS data release, please visit  https://www.sciencebase.gov/about/content/data-release.',\n",
       "   'title': 'USGS Data Release Products'}],\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=&lq=%28title%3A%22USGS+Data+Release+Products%22+AND+body%3A%22data+products%22%29&max=1'},\n",
       " 'took': '1.1s',\n",
       " 'total': 1}"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Find items with \"USGS Data Release Products\" in the title, and \"This\" in the body\n",
    "response = sb.find_items({\n",
    "    'q': '',\n",
    "    'lq': '(title:\"USGS Data Release Products\" AND body:\"data products\")',\n",
    "    'max': 1\n",
    "})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 42721 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 1.0},\n",
       "   'hasChildren': True,\n",
       "   'id': '55b8decde4b09a3b01b61399',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/55b8decde4b09a3b01b61399'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=55b8decde4b09a3b01b61399'}},\n",
       "   'summary': 'Data layers pertaining to the management, restoration, or acquisition designations of state, federal, and non-government organizations (e.g., Focus Areas, Opportunity Areas, Priority Areas, Outstanding Natural Areas) along with the conservation estate (i.e. protected lands) within the Mississippi River Basin and intended to support development of the Multi-LCC Mississippi River Basin/Gulf Hypoxia Initiative’s Conservation Blueprint.',\n",
       "   'title': 'Conservation Designations for Gulf Hypoxia Blueprint'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=&lq=_exists_%3Aextents&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=&lq=_exists_%3Aextents&max=1'},\n",
       " 'took': '451ms',\n",
       " 'total': 42721}"
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Find items that have an extent field. This will find footprinted items.\n",
    "response = sb.find_items({\n",
    "    'q': '',\n",
    "    'lq': '_exists_:extents',\n",
    "    'max': 1\n",
    "})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 4811043 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 0.28593123},\n",
       "   'hasChildren': False,\n",
       "   'id': '542ec027e4b092f17df5ac19',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/542ec027e4b092f17df5ac19'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=542ec027e4b092f17df5ac19'}},\n",
       "   'summary': 'To evaluate the potential effects of climate change on wildlife habitat and ecological integrity in the northeastern United States from 2010 to 2080, a University of Massachusetts Amherst team derived a set of climate projections at a fine spatial resolution for the entire Northeast. The projections are based upon publicly available climate models.This dataset represents the mean of the minimum air temperature (degrees C) for December, January, and February using one of two IPCC greenhouse gas concentration scenarios (RCP8.5). The dataset is intended to represent typical winter temperatures in the decade centered on 2050 rather than the actual temperatures during 2050. MAP UNITS ARE TEMP. IN DEGREES C MULTIPLIED BY 100 (which allows [...]',\n",
       "   'title': 'Mean Minimum Winter Temperature (deg. C) for Northeast, Projected for 2050, RCP8.5, Ensemble GCM Results'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=&lq=files.originalMetadata%3Atrue&max=1&offset=1'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=&lq=files.originalMetadata%3Atrue&max=1'},\n",
       " 'took': '331ms',\n",
       " 'total': 4811043}"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Find items containing files flagged as original metadata\n",
    "response = sb.find_items({\n",
    "    'q': '',\n",
    "    'lq': 'files.originalMetadata:true',\n",
    "    'max': 1\n",
    "})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Search Result Control\n",
    "* `sort` -- sort by `title`, `dateCreated`, `lastUpdated`, or `firstContact`\n",
    "* `order` -- `asc` `desc`\n",
    "* `max` -- max number of items to return per request. Note, ScienceBase enforces an upper limit of 1000.\n",
    "* `offset` -- paging parameter. Return items beginning at `offset`.\n",
    "* `fields` -- specifies which fields in the sbJSON to return, e.g. `title,summary,distributionLinks,webLinks,previewImage`\n",
    "* `fieldset` -- \n",
    "* `loadInstances` -- loads the result items from mongoDB vs. just responding with the elasticsearch response. Some fields, such as `distributionLinks`, are only available from mongoDB, thus the `loadInstances` parameter would be required to fetch those."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 659518 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'id': '58fe0b78e4b00749282945a0',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/58fe0b78e4b00749282945a0'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=58fe0b78e4b00749282945a0'}},\n",
       "   'title': 'Global Surface Water'},\n",
       "  {'id': '55e5c791e4b05561fa208737',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/55e5c791e4b05561fa208737'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=55e5c791e4b05561fa208737'}},\n",
       "   'title': 'Water Quality Data'},\n",
       "  {'id': '547f0d2ee4b09357f05f8ae1',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/547f0d2ee4b09357f05f8ae1'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=547f0d2ee4b09357f05f8ae1'}},\n",
       "   'title': 'Water Quality'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=water&offset=6&max=3&fields=title'},\n",
       " 'prevlink': {'rel': 'previous',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=water&max=3&fields=title'},\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=water&offset=3&max=3&fields=title'},\n",
       " 'took': '131ms',\n",
       " 'total': 659518}"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Return three items from the third page of search results for a \"water\" keyword search, and only return the\n",
    "# 'title' field\n",
    "response = sb.find_items({\n",
    "    'q': 'water',\n",
    "    'offset': 3,\n",
    "    'max': 3,\n",
    "    'fields': 'title'\n",
    "})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Search Facets\n",
    "These parameters control the `searchFacets` section of the results JSON, allowing you to retrieve elasticsearch facet information about your query results. These are not to be confused with `facets` in the Item sbJSON. \n",
    "* enableFacets -- enable the return of the searchFacets section of the results JSON.\n",
    "* facets -- specifies which search facets to return\n",
    "* facetSize -- specifies max the number of entries returned for each search facet\n",
    "* facetTagTypes -- return search facets for the given tag types, e.g. `facetTagTypes=Order,Family,Taxon`\n",
    "* facetTagSchemes -- return search facets for the given tag schemes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 726489 items\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'items': [{'_searchHit': {'_score': 136.56088},\n",
       "   'hasChildren': False,\n",
       "   'id': '5053769be4b097cd4fcdd30f',\n",
       "   'link': {'rel': 'self',\n",
       "    'url': 'https://www.sciencebase.gov/catalog/item/5053769be4b097cd4fcdd30f'},\n",
       "   'relatedItems': {'link': {'rel': 'related',\n",
       "     'url': 'https://www.sciencebase.gov/catalog/itemLinks?itemId=5053769be4b097cd4fcdd30f'}},\n",
       "   'title': 'Water markets and water quality'}],\n",
       " 'nextlink': {'rel': 'next',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=water&enableFacets=True&max=1&facets=browseCategory&offset=1'},\n",
       " 'searchFacets': [{'entries': [{'count': 617705, 'term': 'Physical Item'},\n",
       "    {'count': 87121, 'term': 'Publication'},\n",
       "    {'count': 8229, 'term': 'Data'},\n",
       "    {'count': 1358, 'term': 'Image'},\n",
       "    {'count': 1225, 'term': 'Project'},\n",
       "    {'count': 96, 'term': 'Web Site'},\n",
       "    {'count': 42, 'term': 'Map'}],\n",
       "   'label': 'Categories',\n",
       "   'name': 'browseCategory',\n",
       "   'other': 39,\n",
       "   'total': 715815,\n",
       "   'type': 'terms'}],\n",
       " 'selflink': {'rel': 'self',\n",
       "  'url': 'https://www.sciencebase.gov/catalog/items?q=water&enableFacets=True&max=1&facets=browseCategory'},\n",
       " 'took': '60ms',\n",
       " 'total': 726489}"
      ]
     },
     "execution_count": 38,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Search by the keyword \"water.\" Return the searchFacets section for browseCategory.\n",
    "response = sb.find_items({\n",
    "    'q': 'water',\n",
    "    'enableFacets': True,\n",
    "    'facets': 'browseCategory',\n",
    "    'max': 1\n",
    "})\n",
    "print(\"Found %s items\" % response['total'])\n",
    "response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}