Metadata-Version: 1.2
Name: google_search_results
Version: 1.4.0
Summary: this pip package is meant to scrape and parse Google results using SERP API. Feel free to fork this repository to add more backends.
Home-page: https://github.com/serpapi/google-search-results-python
Author: lf2225
Author-email: lf2225@gmail.com
License: UNKNOWN
Description: # Google Search Results in Python
        
        [![Build Status](https://travis-ci.org/serpapi/google-search-results-python.svg?branch=master)](https://travis-ci.org/serpapi/google-search-results-python)
        
        This Python package is meant to scrape and parse Google results using [SERP API](https://serpapi.com). 
        The following services are provided:
         * [Search API](https://serpapi.com/search-api)
         * [Location API](https://serpapi.com/locations-api)
         * [Search Archive API](https://serpapi.com/search-archive-api)
         * [Account API](https://serpapi.com/account-api)
        
        Serp API provides a [script builder](https://serpapi.com/demo) to get you started quickly.
        
        Feel free to fork this repository to add more backends.
        
        ## Installation
        
        Python 2.7 or 3.7 
        ```bash
        pip install google-search-results
        ```
        
        [Link to the python package page](https://pypi.org/project/google-search-results/)
        
        ## Quick start
        
        ```python
        from lib.google_search_results import GoogleSearchResults
        query = GoogleSearchResults({"q": "coffee", "location": "Austin,Texas"})
        json_results = query.get_json()
         ```
        
        This example runs a search about "coffee" using your secret api key.
        
        The Serp API service (backend)
         - searches on Google using the client: q = "coffee"
         - parses the messy HTML responses
         - return a standardizes JSON response
        The Ruby class GoogleSearchResults
         - Format the request to Serp API server
         - Execute GET http request
         - Parse JSON into Ruby Hash using JSON standard library provided by Ruby
        Et voila..
        
        ## Example
         * [How to set SERP API key](#how-to-set-serp-api-key)
         * [Search API capability](#search-api-capability)
         * [Example by specification](#example-by-specification)
         * [Location API](#location-api)
         * [Search Archive API](#search-archive-api)
         * [Account API](#account-api)
         * [Search Google Images](#search-google-images)
         * [Search Google News](#search-google-news)
         * [Search Google Shopping](#search-google-shopping)
         * [Google Search By Location](#google-search-by-location)
         * [Batch Asynchronous search](#batch-asynchronous-search)
        
        ### How to set SERP API key
        The Serp API key can be set globally using a singleton pattern.
        ```python
        GoogleSearchResults.SERP_API_KEY = "Your Private Key"
        ```
        The Serp API key can be provided for each client.
        ```python
        query = GoogleSearchResults({"q": "coffee", "serp_api_key": "Your Private Key"})
        ```
        
        ### Search API capability
        ```python
        client_params = {
          "q": "client",
          "google_domain": "Google Domain", 
          "location": "Location Requested", 
          "device": "desktop|mobile|tablet",
          "hl": "Google UI Language",
          "gl": "Google Country",
          "safe": "Safe Search Flag",
          "num": "Number of Results",
          "start": "Pagination Offset",
          "serp_api_key": "Your SERP API Key",
          "tbm": "nws|isch|shop"
          "tbs": "custom to be search criteria"
          "async": true|false # allow async 
          "output": "json|html" # output format
        }
        
        # define the search client
        query = GoogleSearchResults[query_params]
        
        # override an existing parameter
        query.params_dict["location"] = "Portland"
        
        # search format return as raw html
        html_results = query.get_html()
        
        # search as raw JSON format
        json_results = query.get_json()
        
        # search as raw Dictionary format
        json_results = query.get_dict()
        ```
        
        (the full documentation)[https://serpapi.com/search-api]
        
        see below for more hands on examples.
        
        ### Example by specification
        
        We love true open source, continuous integration and Test Drive Development (TDD). 
         We are using RSpec to test [our infrastructure around the clock](https://travis-ci.org/serpapi/google-search-results-ruby) to achieve the best QoS (Quality Of Service).
         
        The directory test/ includes specification/examples.
        
        Set your api key.
        ```bash
        export API_KEY="your secret key"
        ```
        
        Run test
        ```python
        make test
        ```
        
        ### Location API
        
        ```python
        client = GoogleSearchResults({})
        location_list = client.get_location("Austin", 3)
        print(location_list)
        ```
        
        it prints the first 3 location matching Austin (Texas, Texas, Rochester)
        ```python
        [   {   'canonical_name': 'Austin,TX,Texas,United States',
                'country_code': 'US',
                'google_id': 200635,
                'google_parent_id': 21176,
                'gps': [-97.7430608, 30.267153],
                'id': '585069bdee19ad271e9bc072',
                'keys': ['austin', 'tx', 'texas', 'united', 'states'],
                'name': 'Austin, TX',
                'reach': 5560000,
                'target_type': 'DMA Region'},
                ...]
        ```
        
        ### Search Archive API
        
        The search result are stored in temporary cached.
        The previous search can be retrieve from the the cache for free.
        
        ```python
        client = GoogleSearchResults({"q": "Coffee", "location": "Austin,Texas"})
        search_result = client.get_dictionary()
        search_id = search_result.get("search_metadata").get("id")
        print(search_id)
        ```
        
        Now let retrieve the previous search from the archive.
        
        ```python
        archived_search_result = GoogleSearchResults({}).get_search_archive(search_id, 'json')
        print(archived_search_result.get("search_metadata").get("id"))
        ```
        it prints the search result from the archive.
        
        ### Account API
        ```python
        client = GoogleSearchResults({})
        account = client.get_account()
        ```
        it prints your account information.
        
        ### Search Google Images
        
        ```python
        client = GoogleSearchResults({"q": "coffe", "tbm": "isch"})
        for image_result in client.get_json()['images_results']:
            link = image_result["original"]
            try:
                print("link: " + link)
                # wget.download(link, '.')
            except:
                pass
        ```
        
        this code prints all the images links, 
         and download image if you un-comment the line with wget (linux/osx tool to download image).
        
        This tutorial covers more ground on this topic.
        https://github.com/serpapi/showcase-serpapi-tensorflow-keras-image-training
        
        ### Search Google News
        
        ```python
        client = GoogleSearchResults({
            "q": "coffe",   # search client
            "tbm": "nws",  # news
            "tbs": "qdr:d", # last 24h
            "num": 10
        })
        for offset in [0,1,2]:
            client.params_dict["start"] = offset * 10
            data = client.get_json()
            for news_result in data['news_results']:
                print(str(news_result['position'] + offset * 10) + " - " + news_result['title'])
        ```
        
        this script prints the first 3 pages of the news title for the last 24h.
        
        ### Search Google Shopping
        
        ```python
        client = GoogleSearchResults({
            "q": "coffe",   # search client
            "tbm": "shop",  # news
            "tbs": "p_ord:rv", # last 24h
            "num": 100
        })
        data = client.get_json()
        for shopping_result in data['shopping_results']:
            print(shopping_result['position']) + " - " + shopping_result['title'])
        
        ```
        
        this script prints all the shopping results order by review order.
        
        ### Google Search By Location
        
        With Serp API, we can build Google search from anywhere in the world.
        This code is looking for the best coffee shop per city.
        
        ```python
        for city in ["new york", "paris", "berlin"]:
          location = GoogleSearchResults({}).get_location(city, 1)[0]["canonical_name"]
          client = GoogleSearchResults({
              "q": "best coffee shop",   # search client
              "location": location,
              "num": 1,
              "start": 0
          })
          data = client.get_json()
          top_result = data["organic_results"][0]["title"]
        ```
        
        ### Batch Asynchronous search
        
        We do offer two ways to boost your searches thanks to `async` parameter.
         - Blocking - async=false - it's more compute intensive because the client would need to hold many connections. (default) 
          - Non-blocking - async=true - it's way to go for large amount of query submitted by batch  (recommended)
        
        TODO add example in python
        
        This code shows a simple implementation to run a batch of asynchronously searches.
        
        ## Conclusion
        SerpAPI supports Google Images, News, Shopping and more..
        To enable a type of search, the field tbm (to be matched) must be set to:
        
         * isch: Google Images API.
         * nws: Google News API.
         * shop: Google Shopping API.
         * any other Google service should work out of the box.
         * (no tbm parameter): regular Google client.
        
        The field `tbs` allows to customize the search even more.
        
        [The full documentation is available here.](https://serpapi.com/search-api)
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2.7
Requires-Python: >=2.6, !=3.0.*, !=3.1.*, !=3.2.*
