{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Call and response: your first Bing Image Search query in Python\n",
    "\n",
    "The Bing Image Search API provides an experience similar to Bing.com/Images by letting you send a user search query to Bing and get back a list of relevant images.\n",
    "\n",
    "This walkthrough demonstrates a simple example of calling into the Bing Image Search API and post-processing the resulting JSON object. For more information, see [Bing Image Search documentation](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-images-api-v7-reference).\n",
    "\n",
    "You can run this example as a Jupyter notebook on [MyBinder](https://mybinder.org) by clicking on the launch Binder badge: \n",
    "\n",
    "[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/Microsoft/cognitive-services-notebooks/master?filepath=BingImageSearchAPI.ipynb)\n",
    "\n",
    "## Prerequisites\n",
    "\n",
    "You must have a [Cognitive Services API account](https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account) with **Bing Search APIs**. The [free trial](https://azure.microsoft.com/try/cognitive-services/?api=bing-web-search-api) is sufficient for this quickstart. You need the access key provided when you activate your free trial, or you may use a paid subscription key from your Azure dashboard.\n",
    "\n",
    "## Running the walkthrough\n",
    "To continue with the walkthrough, set `subscription_key` to your API key for the Bing API service."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "subscription_key = None\n",
    "assert subscription_key"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, verify that the `search_url` endpoint is correct. At this writing, only one endpoint is used for Bing search APIs. If you encounter authorization errors, double-check this value against the Bing search endpoint in your Azure dashboard."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "search_url = \"https://api.cognitive.microsoft.com/bing/v7.0/images/search\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Set `search_term` to look for images of puppies."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "search_term = \"puppies\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following block uses the `requests` library in Python to call out to the Bing search APIs and return the results as a JSON object. Observe that we pass in the API key via the `headers` dictionary and the search term via the `params` dictionary. To see the full list of options that can be used to filter search results, refer to the [REST API](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-images-api-v7-reference) documentation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import requests\n",
    "\n",
    "headers = {\"Ocp-Apim-Subscription-Key\" : subscription_key}\n",
    "params  = {\"q\": search_term, \"license\": \"public\", \"imageType\": \"photo\"}\n",
    "response = requests.get(search_url, headers=headers, params=params)\n",
    "response.raise_for_status()\n",
    "search_results = response.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `search_results` object contains the actual images along with rich metadata such as related items. For example, the following line of code can extract the thumbnail URLS for the first 16 results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "thumbnail_urls = [img[\"thumbnailUrl\"] for img in search_results[\"value\"][:16]]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, we can use the `PIL` library to download the thumbnail images and the `matplotlib` library to render them on a $4 \\times 4$ grid."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "import matplotlib.pyplot as plt\n",
    "from PIL import Image\n",
    "from io import BytesIO\n",
    "\n",
    "f, axes = plt.subplots(4, 4)\n",
    "for i in range(4):\n",
    "    for j in range(4):\n",
    "        image_data = requests.get(thumbnail_urls[i+4*j])\n",
    "        image_data.raise_for_status()\n",
    "        image = Image.open(BytesIO(image_data.content))        \n",
    "        axes[i][j].imshow(image)\n",
    "        axes[i][j].axis(\"off\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next steps\n",
    "\n",
    "> [!div class=\"nextstepaction\"]\n",
    "> [Bing Image Search single-page app tutorial](../tutorial-bing-image-search-single-page-app.md)\n",
    "\n",
    "## See also \n",
    "\n",
    "[Bing Image Search overview](../overview.md)  \n",
    "[Try it](https://azure.microsoft.com/services/cognitive-services/bing-image-search-api/)  \n",
    "[Get a free trial access key](https://azure.microsoft.com/try/cognitive-services/?api=bing-image-search-api)  \n",
    "[Bing Image Search API reference](https://docs.microsoft.com/rest/api/cognitiveservices/bing-images-api-v7-reference)"
   ]
  }
 ],
 "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.3"
  },
  "ms_docs_meta": {
   "author": "jerrykindall",
   "description": "Get information and code samples to help you quickly get started using the Bing Image Search API in Microsoft Cognitive Services on Azure.",
   "documentationcenter": "''",
   "ms.author": "v-jerkin",
   "ms.date": "9/21/2017",
   "ms.service": "cognitive-services",
   "ms.technology": "bing-search",
   "ms.topic": "article",
   "services": "cognitive-services",
   "title": "Call and response - Python Quickstart for Azure Cognitive Services, Bing Image Search API | Microsoft Docs"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}