From 872c50ef03b22ae3da632411318e919f19f07471 Mon Sep 17 00:00:00 2001
From: Kelly Lockhart <2926089+kelockhart@users.noreply.github.com>
Date: Fri, 21 Feb 2020 12:40:13 -0500
Subject: [PATCH] Updated info on sorting by date

---
 Search_API.ipynb | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Search_API.ipynb b/Search_API.ipynb
index 72b4049..a94cd40 100644
--- a/Search_API.ipynb
+++ b/Search_API.ipynb
@@ -267,7 +267,7 @@
     "Filters the list of search results. The syntax is the same as that for the `q` parameter. Adding search parameters via the `fq` parameter can speed up search results, as it searches only the results returned by the search entered via the `q` parameter, not the entire index. This parameter may be used more than once in a single search URL.\n",
     "\n",
     "#### sort\n",
-    "The sorting field and direction to be used when returning results. The format requires both the field to sort on (see [the list below](#fields) and the direction, either `asc` or `desc` (ascending or descending). For example, an appropriately formatted sort parameter is `sort=citation_count+desc`. The default sort method is the relevancy score as calculated by the search engine. Other useful fields to sort on may be `pubdate`, `read_count`, `first_author`, or `bibcode`."
+    "The sorting field and direction to be used when returning results. The format requires both the field to sort on (see [the list below](#fields) and the direction, either `asc` or `desc` (ascending or descending). For example, an appropriately formatted sort parameter is `sort=citation_count+desc`. The default sort method is the relevancy score as calculated by the search engine. Other useful fields to sort on may be `date`, `read_count`, `first_author`, or `bibcode`."
    ]
   },
   {
@@ -275,7 +275,9 @@
    "metadata": {},
    "source": [
     "## Fields\n",
-    "This is a non-exhaustive list of fields available for searching via the API. A more comprehensive list is available in our [help pages](https://adsabs.github.io/help/search/comprehensive-solr-term-list). These fields can be used with the `fl` and `sort` parameters.\n",
+    "This is a non-exhaustive list of fields available for searching via the API. A more comprehensive list is available in our [help pages](https://adsabs.github.io/help/search/comprehensive-solr-term-list). These fields can be used with the `fl` and `sort` parameters. \n",
+    "\n",
+    "Note: some fields, such as body, can be searched but not returned via `fl` or sorted on. Also, multivalued fields, such as author, cannot be used for sorting.\n",
     "\n",
     "* `abstract` - the abstract of the record\n",
     "* `ack` - the acknowledgements section of an article\n",
@@ -291,6 +293,7 @@
     "* `citation_count` - number of citations the item has received\n",
     "* `copyright` - the copyright applied to the article\n",
     "* `data` - the list of sources that have data related to this bibcode\n",
+    "* `date` - the machine-readable version of `pubdate`, useful for sorting\n",
     "* `database` - database the record is associated with (astronomy, physics, or general). By default, all three databases are searched; to limit to astronomy articles, add `fq=database:astronomy` to the URL\n",
     "* `doi`-  the digital object identifier of the article\n",
     "* `doctype` - the type of document it is (see [here](https://adsabs.github.io/help/search/search-syntax) for a list of doctypes)\n",
@@ -308,7 +311,7 @@
     "* `page` - starting page\n",
     "* `property` - an array of miscellaneous flags associated with the record (see [here](https://adsabs.github.io/help/search/search-syntax) for a list of properties\n",
     "* `pub` - the canonical name of the publication the record appeared in\n",
-    "* `pubdate` - publication date in the form YYYY-MM-DD (DD value will always be \"00\")\n",
+    "* `pubdate` - publication date in the form YYYY-MM-DD (DD value will always be \"00\"). This field is stored as a human-readable string, so is useful for being returned via `fl`, but not for sorting (see `date`)\n",
     "* `read_count` - number of times the record has been viewed within in a 90-day windows (ads and arxiv)\n",
     "* `title` - the title of the record\n",
     "* `vizier` - the subject tags given to the article by VizieR\n",