examples/Working with Cornershop models.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `Cornershop`\n",
    "\n",
    "Import the Cornershop API model from the `cornershop` module e instanciate it using a desired zip code as locality.\n",
    "\n",
    "The API contains four methods:\n",
    "- `search_branches`: The main method for searching products in every store near your locality.\n",
    "- `search_branch`: Search for a specific store.\n",
    "- `search_branch_group`: Get a list of categories of stores.\n",
    "- `search_countries`: Get a list of countries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from cornershop import Cornershop\n",
    "\n",
    "cs = Cornershop(\n",
    "    locality = 80530190,\n",
    "    country = 'BR'\n",
    ")\n",
    "\n",
    "# Methods\n",
    "cs.search_branch\n",
    "cs.search_branches\n",
    "cs.search_branch_groups\n",
    "cs.search_countries"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `Result`\n",
    "\n",
    "We get a list of `Results` models when searching branches.\n",
    "\n",
    "Theses models contains two attributes:\n",
    "- `store`: The store related to the query.\n",
    "- `search_result`: The list of aisles and products related to the query in this particular store."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<cornershop.models.Result: \"amaciante\" on Carrefour Hiper>,\n",
       " <cornershop.models.Result: \"amaciante\" on Big>,\n",
       " <cornershop.models.Result: \"amaciante\" on Nacional>,\n",
       " <cornershop.models.Result: \"amaciante\" on Muffato>,\n",
       " <cornershop.models.Result: \"amaciante\" on Assaí>,\n",
       " <cornershop.models.Result: \"amaciante\" on Maxxi>,\n",
       " <cornershop.models.Result: \"amaciante\" on Atacadão>,\n",
       " <cornershop.models.Result: \"amaciante\" on Muffato Gourmet>,\n",
       " <cornershop.models.Result: \"amaciante\" on Max Atacadista>,\n",
       " <cornershop.models.Result: \"amaciante\" on Sam's Club>,\n",
       " <cornershop.models.Result: \"amaciante\" on Casa Fiesta>,\n",
       " <cornershop.models.Result: \"amaciante\" on Fiesta Express>]"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "results = cs.search_branches(query='amaciante')\n",
    "results"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<cornershop.models.Store: Carrefour Hiper>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "results[0].store"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<cornershop.models.SearchResult: amaciante>"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "results[0].search_result"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `Store`\n",
    "\n",
    "Access the `Store` model inside a `Result` model by its `store` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<cornershop.models.Store: Carrefour Hiper>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "store = results[0].store\n",
    "store"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It contains same useful attributes about the store."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_keys(['id', 'name', 'country', 'locale', 'priority', 'img_url', 'light_img_url', 'self_picking', 'self_delivery', 'minimum_amount', 'maximum_amount', 'closest_branch', 'is_published', 'description', 'description_disclaimer'])"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "store.__dict__.keys()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `SearchResult`\n",
    "\n",
    "Access the `SearchResult` model inside a `Result` model by its `search_result` attribute.\n",
    "\n",
    "It contains two attributes:\n",
    "- `search_term`: The term you passed through the query argument of the `search_branches` method.\n",
    "- `aisles`: A list of aisles containing a list of products related to the search term."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<cornershop.models.SearchResult: amaciante>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "search_result = results[0].search_result\n",
    "search_result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<cornershop.models.Aisle: C_1582 - Amaciantes>]"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "search_result.aisles"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `Aisle`\n",
    "\n",
    "Access a list of `Aisle` models inside a `SearchResult` model by its `aisles` attribute.\n",
    "\n",
    "Each `Aisle` model contains the aisle identification and a list of `Product` models."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<cornershop.models.Aisle: C_1582 - Amaciantes>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "aisle = search_result.aisles[0]\n",
    "aisle"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Aisle ID: C_1582\n",
      "Aisle name: Amaciantes\n",
      "Department ID: C_983\n"
     ]
    }
   ],
   "source": [
    "print(f'Aisle ID: {aisle.aisle_id}')\n",
    "print(f'Aisle name: {aisle.aisle_name}')\n",
    "print(f'Department ID: {aisle.department_id}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<cornershop.models.Product: 1191770 - Amaciante de roupa concentrado brisa de verão>,\n",
       " <cornershop.models.Product: 1191812 - Amaciante de roupas intenso>,\n",
       " <cornershop.models.Product: 1191787 - Amaciante de roupa concentrado intense>,\n",
       " <cornershop.models.Product: 1472463 - Amaciante de roupa mon biju pureza>,\n",
       " <cornershop.models.Product: 1191775 - Amaciante de roupas concentrado brisa de verão>]"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "aisle.products[:5]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `Product`\n",
    "\n",
    "Access a list of `Product` models inside a `Aisle` model by its `products` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<cornershop.models.Product: 1191770 - Amaciante de roupa concentrado brisa de verão>"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "product = aisle.products[0]\n",
    "product"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It contains same useful information about the product."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_keys(['id', 'brand', 'kind', 'related_to', 'buy_unit', 'default_buy_unit', 'variable_weight', 'currency', 'unit_conversion_rate', 'purchasable', 'pricing', 'price_per_unit', 'regulatory_fees', 'price', 'original_price', 'label', 'description_sections', 'availability_status', 'nutritional_info', 'name', 'description', 'package', 'img_url', 'extra_img_urls'])"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "product.__dict__.keys()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `Group`\n",
    "\n",
    "We get a list of `Group` models when searching for branch groups.\n",
    "\n",
    "This model contains some identification attributes and an `items` attribute containing a list of stores related to this category."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<cornershop.model.Group: Destacados>,\n",
       " <cornershop.model.Group: Atacadistas>,\n",
       " <cornershop.model.Group: Entregas rápidas>,\n",
       " <cornershop.model.Group: Destacados>,\n",
       " <cornershop.model.Group: Farmácia>,\n",
       " <cornershop.model.Group: Animais de estimação>,\n",
       " <cornershop.model.Group: Vinhos e bebidas>,\n",
       " <cornershop.model.Group: Vida saudável>,\n",
       " <cornershop.model.Group: Beleza e cuidados pessoais>,\n",
       " <cornershop.model.Group: Gourmet>,\n",
       " <cornershop.model.Group: Supermercados>,\n",
       " <cornershop.model.Group: Outras lojas>]"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Search branch group near your locality\n",
    "groups = cs.search_branch_groups()\n",
    "groups"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Destacados'"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "groups[0].name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<cornershop.model.GroupItem: Big>,\n",
       " <cornershop.model.GroupItem: Carrefour Hiper>,\n",
       " <cornershop.model.GroupItem: Nacional>,\n",
       " <cornershop.model.GroupItem: Muffato>,\n",
       " <cornershop.model.GroupItem: Muffato Gourmet>,\n",
       " <cornershop.model.GroupItem: Cobasi>,\n",
       " <cornershop.model.GroupItem: Atacadão>,\n",
       " <cornershop.model.GroupItem: Assaí>,\n",
       " <cornershop.model.GroupItem: Maxxi>,\n",
       " <cornershop.model.GroupItem: Sam's Club>,\n",
       " <cornershop.model.GroupItem: Granado Pharmácias>,\n",
       " <cornershop.model.GroupItem: Max Atacadista>]"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "groups[0].items"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `GroupItem`\n",
    "\n",
    "Access a list of `GroupItem` models inside a `Group` model by its `items` attribute.\n",
    "\n",
    "This model contains some information about the store used in the Cornershop app front-end."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<cornershop.model.GroupItem: Big>,\n",
       " <cornershop.model.GroupItem: Carrefour Hiper>,\n",
       " <cornershop.model.GroupItem: Nacional>,\n",
       " <cornershop.model.GroupItem: Muffato>,\n",
       " <cornershop.model.GroupItem: Muffato Gourmet>,\n",
       " <cornershop.model.GroupItem: Cobasi>,\n",
       " <cornershop.model.GroupItem: Atacadão>,\n",
       " <cornershop.model.GroupItem: Assaí>,\n",
       " <cornershop.model.GroupItem: Maxxi>,\n",
       " <cornershop.model.GroupItem: Sam's Club>,\n",
       " <cornershop.model.GroupItem: Granado Pharmácias>,\n",
       " <cornershop.model.GroupItem: Max Atacadista>]"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "item = groups[0].items\n",
    "item"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'type': 'branch',\n",
       " 'badges': [],\n",
       " 'brand_color': '0072ce',\n",
       " 'excerpt': 'Bom. Big. Barato',\n",
       " 'id': '8027',\n",
       " 'img_url': 'https://s.cornershopapp.com/store-logo/big-br-light.png?versionId=xo6Ewy9wK_v0VAk927HeEqQ3tk2KwmOk',\n",
       " 'name': 'Big',\n",
       " 'poster': {'imageset': {'1x': 'https://s.cornershopapp.com/store-poster/1481-big-1x.jpeg?versionId=lZPBxKQjtQGYBuFr6iujc5euO7_yJ9.5',\n",
       "   '2x': 'https://s.cornershopapp.com/store-poster/1481-big-2x.jpeg?versionId=ZfCU2O_8X3FGWhJpxeE_fQi5Y842b05r',\n",
       "   '3x': 'https://s.cornershopapp.com/store-poster/1481-big-3x.jpeg?versionId=cfdvWwAkftXR.Ggmo_5GUYeSvN3xXPeM'}},\n",
       " 'pricing_notes': {'title': '3% taxa de serviço',\n",
       "  'description': 'Os preços dos produtos são publicados pela loja Big. A Cornershop cobra uma taxa de serviço que você poderá ver antes de efetuar o pagamento em \"Taxa de serviço\".',\n",
       "  'disclaimer': 'Os preços dos produtos são publicados pela loja Big. A Cornershop cobra uma taxa de serviço que você poderá ver antes de efetuar o pagamento em \"Taxa de serviço\".'},\n",
       " 'store_id': '1481'}"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "item[0].__dict__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `Branch`\n",
    "\n",
    "Search for a specific branch using its `id` and a search query.\n",
    "\n",
    "Get a list of `Aisle` model with the `aisles` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<cornershop.models.Branch>"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Use a seach query on a specific branch\n",
    "branch = cs.search_branch(\n",
    "    branch_id = 8027,\n",
    "    query = 'amaciante'\n",
    ")\n",
    "branch"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<cornershop.models.Aisle: promotions - Produtos em promoção>,\n",
       " <cornershop.models.Aisle: C_1582 - Amaciantes>,\n",
       " <cornershop.models.Aisle: C_81 - Temperos para preparação carne>,\n",
       " <cornershop.models.Aisle: C_984 - Lavanderia>]"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "branch.aisles"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `Country`\n",
    "\n",
    "Get a list of `Country` models with the `search_countries` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<cornershop.models.Country: Brasil>,\n",
       " <cornershop.models.Country: Canada>,\n",
       " <cornershop.models.Country: Chile>,\n",
       " <cornershop.models.Country: Colombia>,\n",
       " <cornershop.models.Country: Costa Rica>,\n",
       " <cornershop.models.Country: México>,\n",
       " <cornershop.models.Country: Perú>,\n",
       " <cornershop.models.Country: United States>]"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "countries = cs.search_countries()\n",
    "countries"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It contains some useful information about the country."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'country': 'BR',\n",
       " 'name': 'Brasil',\n",
       " 'locality_fields': ['zip_code'],\n",
       " 'fields': {'zip_code': {'required': True,\n",
       "   'free_text': True,\n",
       "   'label': 'Código postal',\n",
       "   'default_value': ''}},\n",
       " 'cities': [{'name': 'São Paulo'},\n",
       "  {'name': 'Belo Horizonte'},\n",
       "  {'name': 'Brasília'},\n",
       "  {'name': 'Curitiba'},\n",
       "  {'name': 'Fortaleza'},\n",
       "  {'name': 'Goiânia'},\n",
       "  {'name': 'Manaus'},\n",
       "  {'name': 'Porto Alegre'},\n",
       "  {'name': 'Recife'},\n",
       "  {'name': 'Rio de Janeiro'},\n",
       "  {'name': 'Salvador'},\n",
       "  {'name': 'Other'}]}"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "countries[0].__dict__"
   ]
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "b3ba2566441a7c06988d0923437866b63cedc61552a5af99d1f4fb67d367b25f"
  },
  "kernelspec": {
   "display_name": "Python 3.7.7 64-bit ('base': conda)",
   "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.7.7"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}