00_parser.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# default_exp parser"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Trove query parser\n",
    "\n",
    "> Use `parse_query` to convert a search query from the Trove web interface into a set of parameters that the API will understand."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#hide\n",
    "from nbdev.showdoc import *\n",
    "\n",
    "%load_ext dotenv\n",
    "%dotenv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Functions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "\n",
    "import os\n",
    "from urllib.parse import urlparse, parse_qsl, parse_qs\n",
    "import requests\n",
    "import arrow\n",
    "\n",
    "def format_date(date, start=False):\n",
    "    '''\n",
    "    The web interface uses YYYY-MM-DD dates, but the API expects YYYY-MM-DDT00:00:00Z. Reformat dates accordingly.\n",
    "    \n",
    "    Also the start date in an API query needs to be set to the day before you want. So if this is a start date, take it back in time by a day.\n",
    "    '''\n",
    "    if date != '*':\n",
    "        date_obj = arrow.get(date)\n",
    "        if start:\n",
    "            date_obj = date_obj.shift(days=-1)\n",
    "        date = '{}Z'.format(date_obj.format('YYYY-MM-DDT00:00:00'))\n",
    "    return date\n",
    "\n",
    "def parse_query(query, api_version=2):\n",
    "    '''\n",
    "    Converts the parameters of a search using the Trove web interface into a form the API will understand.\n",
    "    \n",
    "    Parameters:  \n",
    "    * `query` – the url of a search in the Trove newspapers & gazettes category\n",
    "    * `api_version` – Trove API version (default is 2)\n",
    "    \n",
    "    Returns:  \n",
    "    * a dict containing the parameters (multiple values will be in a list)\n",
    "    '''\n",
    "    parsed_url = urlparse(query)\n",
    "    if 'api.trove.nla.gov.au' in query:\n",
    "        # If it's an API url, no further processing of parameters needed\n",
    "        new_params = parse_qs(parsed_url.query)\n",
    "    else:\n",
    "        # These params can be accepted as is.\n",
    "        safe = ['l-category', 'l-title', 'l-decade', 'l-year', 'l-month', 'l-state', 'include']\n",
    "        new_params = {}\n",
    "        dates = {}\n",
    "        keywords = []\n",
    "        params = parse_qsl(parsed_url.query)\n",
    "        # Loop through all the parameters\n",
    "        for key, value in params:\n",
    "            if key in safe:\n",
    "                try:\n",
    "                    new_params[key].append(value)\n",
    "                except KeyError:\n",
    "                    new_params[key] = [value]\n",
    "            elif key in ['l-word', 'l-advWord']:\n",
    "                if api_version == 2:\n",
    "                    new_params['l-word'] = value\n",
    "                elif api_version == 3:\n",
    "                    new_params['l-wordCount'] = value\n",
    "            elif key == 'l-advstate':\n",
    "                try:\n",
    "                    new_params['l-state'].append(value)\n",
    "                except KeyError:\n",
    "                    new_params['l-state'] = [value]\n",
    "            elif key == 'l-advcategory':\n",
    "                try:\n",
    "                    new_params['l-category'].append(value)\n",
    "                except KeyError:\n",
    "                    new_params['l-category'] = [value]\n",
    "            elif key == 'l-advtitle':\n",
    "                try:\n",
    "                    new_params['l-title'].append(value)\n",
    "                except KeyError:\n",
    "                    new_params['l-title'] = [value]\n",
    "            elif key in ['l-illustrationType', 'l-advIllustrationType']:\n",
    "                new_params['l-illustrated'] = 'true'\n",
    "                if api_version == 2:\n",
    "                    new_params['l-illtype'] = [value]\n",
    "                elif api_version == 3:\n",
    "                    new_params['l-illustrationType'] = [value]\n",
    "            elif key == 'date.from':\n",
    "                dates['from'] = value\n",
    "            elif key == 'date.to':\n",
    "                dates['to'] = value\n",
    "            elif key == 'keyword':\n",
    "                new_params['q'] = value\n",
    "            elif key == 'keyword.phrase':\n",
    "                keywords.append('\"{}\"'.format(value))\n",
    "            elif key == 'keyword.not':\n",
    "                keywords.append('NOT ({})'.format(' OR '.join(value.split())))\n",
    "            elif key == 'keyword.any':\n",
    "                keywords.append('({})'.format(' OR '.join(value.split())))\n",
    "            elif key in ['l-ArtType', 'l-advArtType', 'l-artType']:\n",
    "                if api_version == 2:\n",
    "                    if value == 'newspapers':\n",
    "                        new_params['zone'] = 'newspaper'\n",
    "                    elif value == 'gazette':\n",
    "                        new_params['zone'] = 'gazette'\n",
    "                elif api_version == 3:\n",
    "                    new_params['l-artType'] = value\n",
    "        if keywords:\n",
    "            if 'q' in new_params:\n",
    "                new_params['q'] += ' AND {}'.format(' AND '.join(keywords))\n",
    "            else:\n",
    "                new_params['q'] = ' AND '.join(keywords)\n",
    "        if dates:\n",
    "            if 'from' not in dates:\n",
    "                dates['from'] = '*'\n",
    "            if 'to' not in dates:\n",
    "                dates['to'] = '*'\n",
    "            date_query = 'date:[{} TO {}]'.format(format_date(dates['from'], True), format_date(dates['to']))\n",
    "            if 'q' in new_params:\n",
    "                new_params['q'] += ' {}'.format(date_query)\n",
    "            else:\n",
    "                new_params['q'] = date_query\n",
    "        if 'q' not in new_params:\n",
    "            new_params['q'] = ' '\n",
    "        if api_version == 2 and 'zone' not in new_params:\n",
    "            new_params['zone'] = 'newspaper,gazette'\n",
    "        if api_version == 3 and 'category' not in new_params:\n",
    "            new_params['category'] = 'newspaper'\n",
    "    # return '{}?{}'.format('https://api.trove.nla.gov.au/v2/result', urlencode(new_params, doseq=True))\n",
    "    return new_params"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "show_doc(parse_query)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic usage"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's the url of a search in Trove's newspapers: https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-state=Queensland&l-category=Article&l-illustrationType=Cartoon\n",
    "\n",
    "If we feed this url to `parse_query()` we get back a dict with the query parameters translated into a form the Trove API understands."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-state=Queensland&l-category=Article&l-illustrationType=Cartoon', 3)\n",
    "params"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to use this to get data back from the Trove API, you'll need to provide your Trove API key, either as a query parameter (version 2), or in the request headers (version 3). You might also want to change the `encoding` of the results to 'json'. Then you can just give the parameters as `params` to `requests`. For example:\n",
    "\n",
    "``` python\n",
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-state=Queensland&l-category=Article&l-illustrationType=Cartoon', 3)\n",
    "headers = {'X-API-KEY': 'mYApiKEY'}\n",
    "params['encoding'] = 'json'\n",
    "params['n'] = 1\n",
    "response = requests.get('https://api.trove.nla.gov.au/v3/result', params=params, headers=headers)\n",
    "data = response.json()\n",
    "```\n",
    "\n",
    "Assuming your API key is valid, this will return the following results:\n",
    "\n",
    "``` python\n",
    "{'query': 'wragge',\n",
    " 'category': [{'code': 'newspaper',\n",
    "   'name': 'Newspapers & Gazettes',\n",
    "   'records': {'s': '*',\n",
    "    'n': 2,\n",
    "    'total': 510,\n",
    "    'next': 'https://api.trove.nla.gov.au/v3/result?q=wragge&l-artType=newspapers&l-state=Queensland&l-category=Article&l-illustrated=true&l-illtype=Cartoon&category=newspaper&encoding=json&n=2&s=AoIIQzWFoig4MjM0NjM1NA%3D%3D',\n",
    "    'nextStart': 'AoIIQzWFoig4MjM0NjM1NA==',\n",
    "    'article': [{'id': '21765046',\n",
    "      'url': 'https://api.trove.nla.gov.au/v3/newspaper/21765046',\n",
    "      'heading': 'Mrs. Adelaide Wragge.',\n",
    "      'category': 'Article',\n",
    "      'title': {'id': '16',\n",
    "       'title': 'The Brisbane Courier (Qld. : 1864 - 1933)'},\n",
    "      'date': '1931-12-16',\n",
    "      'page': '13',\n",
    "      'pageSequence': '13',\n",
    "      'relevance': {'score': 215.65185546875, 'value': 'very relevant'},\n",
    "      'snippet': 'Formerly of Victoria, and in 1864 Mayoress of Melbourne, the late Mrs. Wragge, who died recently, had been',\n",
    "      'troveUrl': 'https://.nla.gov.au/nla.news-article21765046?searchTerm=wragge'},\n",
    "     {'id': '82346354',\n",
    "      'url': 'https://api.trove.nla.gov.au/v3/newspaper/82346354',\n",
    "      'heading': 'MR WRAGGE ON WEATHER CANNONS.',\n",
    "      'category': 'Article',\n",
    "      'title': {'id': '269',\n",
    "       'title': 'The North Queensland Register (Townsville, Qld. : 1892 - 1905)'},\n",
    "      'date': '1901-03-11',\n",
    "      'page': '10',\n",
    "      'pageSequence': '10',\n",
    "      'relevance': {'score': 181.52200317382812, 'value': 'very relevant'},\n",
    "      'snippet': 'I have been to Styria, have seen the cannons made in the forges, have witnessed the experiments, have visited Herr Stiger, the inventor of the',\n",
    "      'troveUrl': 'https://.nla.gov.au/nla.news-article82346354?searchTerm=wragge'}]}}]}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the API includes some additional parameters such as `reclevel` and `include`. Have a look at the [Trove API Console](https://troveconsole.herokuapp.com/) for examples."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Version 2 tests"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Simple search with facets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Multiple keywords are just passed along as is and are combined with a boolean `AND`. This is the same in both the Simple and Advanced search."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge weather', 'zone': 'newspaper,gazette'} == parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge%20weather')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Multiple keywords with `OR` are passed along as is."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge OR weather', 'zone': 'newspaper,gazette'} == parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge%20OR%20weather')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Phrase search passed along as is."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': '\"inclement wragge\"', 'zone': 'newspaper,gazette'} == parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=%22inclement%20wragge%22')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More complex queries such as date ranges should be passed along as is."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge%20date%3A%5B1901%20TO%201903%5D&l-artType=newspapers')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to gazettes using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge', 'zone': 'gazette'} == parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=gazette')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit state to NSW using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge', 'l-state': ['New South Wales'], 'zone': 'newspaper,gazette'} == parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-state=New%20South%20Wales')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit newspaper to SMH using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge', 'zone': 'newspaper', 'l-title': ['35']} == parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-title=35')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to 'Article' category using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge', 'zone': 'newspaper', 'l-category': ['Article']} == parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-category=Article')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to specific decade using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-decade=190')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to specific year using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-decade=190&l-year=1903')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to articles with illustration type of 'Photo' with facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge', 'zone': 'newspaper', 'l-illustrated': 'true', 'l-illtype': ['Photo']} == parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-illustrationType=Photo')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to articles containing more than 1,000 words using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge', 'zone': 'newspaper', 'l-word': '1000+ Words'} == parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-word=1000%2B%20Words')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Advanced search"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Multiple keywords in 'Any of these words' box."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': '(wragge OR weather)', 'zone': 'newspaper,gazette'} == parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword.any=wragge%20weather')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Multiple keywords in 'The phrase' box."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': '\"inclement wragge\"', 'zone': 'newspaper,gazette'} == parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword.phrase=inclement%20wragge')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Keywords in 'All of these words' and 'Without these words' boxes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge AND NOT (weather)', 'zone': 'newspaper,gazette'} == parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword.not=weather&keyword=wragge')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to a specific date range."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge date:[1899-12-31T00:00:00Z TO 1900-02-04T00:00:00Z]', 'zone': 'newspaper'} == parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword=wragge&date.from=1900-01-01&date.to=1900-02-04&l-advArtType=newspapers')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to a specific state."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge', 'zone': 'newspaper', 'l-state': ['Queensland']} == parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword=wragge&l-advArtType=newspapers&l-advstate=Queensland')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to specific newspapers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge', 'zone': 'newspaper', 'l-title': ['16', '1055']} == parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword=wragge&l-advArtType=newspapers&l-advtitle=16&l-advtitle=1055')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to a specific category."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge', 'zone': 'newspaper', 'l-category': ['Family Notices']} == parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword=wragge&l-advArtType=newspapers&l-advcategory=Family%20Notices')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to a specific illustration type."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge', 'zone': 'newspaper', 'l-illustrated': 'true', 'l-illtype': ['Photo']} == parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword=wragge&l-advArtType=newspapers&l-advIllustrationType=Photo')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to a specific number of words."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert {'q': 'wragge', 'zone': 'newspaper', 'l-word': '100 - 1000 Words'} == parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword=wragge&l-advArtType=newspapers&l-advWord=100%20-%201000%20Words')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Version 3 tests"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Simple search with facets"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def query_api(params):\n",
    "    api_key = os.getenv(\"TROVE_API_KEY\")\n",
    "    params[\"n\"] = 0\n",
    "    response = requests.get(\"https://api.trove.nla.gov.au/v3/result\", params=params, headers={\"X-API-KEY\": api_key})\n",
    "    return response.status_code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge%20weather', 3)\n",
    "assert {'q': 'wragge weather', 'category': 'newspaper'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Multiple keywords with `OR` are passed along as is."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge%20OR%20weather', 3)\n",
    "assert {'q': 'wragge OR weather', 'category': 'newspaper'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Phrase search passed along as is."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=%22inclement%20wragge%22', 3)\n",
    "assert {'q': '\"inclement wragge\"', 'category': 'newspaper'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More complex queries such as date ranges should be passed along as is."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge%20date%3A%5B1901%20TO%201903%5D&l-artType=newspapers', 3)\n",
    "assert {'q': 'wragge date:[1901 TO 1903]', 'category': 'newspaper', 'l-artType': 'newspapers'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to gazettes using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=gazette', 3)\n",
    "assert {'q': 'wragge', 'category': 'newspaper', 'l-artType': 'gazette'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit state to NSW using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-state=New%20South%20Wales', 3)\n",
    "assert {'q': 'wragge', 'l-state': ['New South Wales'], 'category': 'newspaper'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit newspaper to SMH using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-title=35', 3)\n",
    "assert {'q': 'wragge', 'category': 'newspaper', 'l-title': ['35'], 'l-artType': 'newspapers'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to 'Article' category using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-category=Article', 3)\n",
    "assert {'q': 'wragge', 'category': 'newspaper', 'l-category': ['Article'], 'l-artType': 'newspapers'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to specific decade using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-decade=190', 3)\n",
    "assert {'q': 'wragge', 'l-artType': 'newspapers', 'l-decade': ['190'], 'category': 'newspaper'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to specific year using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-decade=190&l-year=1903', 3)\n",
    "assert {'q': 'wragge', 'l-artType': 'newspapers', 'l-decade': ['190'], 'l-year': ['1903'], 'category': 'newspaper'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to articles with illustration type of 'Photo' with facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-illustrationType=Photo', 3)\n",
    "assert {'q': 'wragge', 'category': 'newspaper', 'l-illustrated': 'true', 'l-illustrationType': ['Photo'], 'l-artType': 'newspapers'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to articles containing more than 1,000 words using facets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/category/newspapers?keyword=wragge&l-artType=newspapers&l-word=1000%2B%20Words', 3)\n",
    "assert {'q': 'wragge', 'category': 'newspaper', 'l-wordCount': '1000+ Words', 'l-artType': 'newspapers'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Advanced search"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Multiple keywords in 'Any of these words' box."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword.any=wragge%20weather', 3)\n",
    "assert {'q': '(wragge OR weather)', 'category': 'newspaper'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Multiple keywords in 'The phrase' box."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword.phrase=inclement%20wragge', 3)\n",
    "assert {'q': '\"inclement wragge\"', 'category': 'newspaper'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Keywords in 'All of these words' and 'Without these words' boxes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword.not=weather&keyword=wragge', 3)\n",
    "assert {'q': 'wragge AND NOT (weather)', 'category': 'newspaper'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to a specific date range."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword=wragge&date.from=1900-01-01&date.to=1900-02-04&l-advArtType=newspapers', 3)\n",
    "assert {'q': 'wragge date:[1899-12-31T00:00:00Z TO 1900-02-04T00:00:00Z]', 'category': 'newspaper', 'l-artType': 'newspapers'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to a specific state."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword=wragge&l-advArtType=newspapers&l-advstate=Queensland', 3)\n",
    "assert {'q': 'wragge', 'category': 'newspaper', 'l-state': ['Queensland'], 'l-artType': 'newspapers'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to specific newspapers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword=wragge&l-advArtType=newspapers&l-advtitle=16&l-advtitle=1055', 3)\n",
    "assert {'q': 'wragge', 'category': 'newspaper', 'l-title': ['16', '1055'], 'l-artType': 'newspapers'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to a specific category."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword=wragge&l-advArtType=newspapers&l-advcategory=Family%20Notices', 3)\n",
    "assert {'q': 'wragge', 'category': 'newspaper', 'l-category': ['Family Notices'], 'l-artType': 'newspapers'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to a specific illustration type."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword=wragge&l-advArtType=newspapers&l-advIllustrationType=Photo', 3)\n",
    "assert {'q': 'wragge', 'category': 'newspaper', 'l-illustrated': 'true', 'l-illustrationType': ['Photo'], 'l-artType': 'newspapers'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Limit to a specific number of words."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = parse_query('https://trove.nla.gov.au/search/advanced/category/newspapers?keyword=wragge&l-advArtType=newspapers&l-advWord=100%20-%201000%20Words', 3)\n",
    "assert {'q': 'wragge', 'category': 'newspaper', 'l-wordCount': '100 - 1000 Words', 'l-artType': 'newspapers'} == params\n",
    "assert query_api(params) == 200"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}