Module google

[show private | hide private]
[frames | no frames]

## Module google

Python wrapper for Google web APIs

This module allows you to access Google's web APIs through SOAP, to do things like search Google and get the results programmatically. Described here

You need a Google-provided license key to use these services. Follow the link above to get one. These functions will look in several places (in this order) for the license key:

- the "license_key" argument of each function
- the module-level LICENSE_KEY variable (call setLicense once to set it)
- an environment variable called GOOGLE_LICENSE_KEY
- a file called ".googlekey" in the current directory
- a file called "googlekey.txt" in the current directory
- a file called ".googlekey" in your home directory
- a file called "googlekey.txt" in your home directory
- a file called ".googlekey" in the same directory as google.py
- a file called "googlekey.txt" in the same directory as google.py

Sample usage:

       >>> import google
       >>> google.setLicense('...') # must get your own key!
       >>> data = google.doGoogleSearch('python')
       >>> data.meta.searchTime
       0.043221000000000002

       >>> data.results[0].URL
       'http://www.python.org/'

       >>> data.results[0].title
       '<b>Python</b> Language Website'

Version: 0.6

Authors:
  Mark Pilgrim <f8dy@diveintomark.org>, Brian Landers <brian@bluecoat93.org>

License: Python

Contributors:

- David Ascher, for the install script
- Erik Max Francis, for the command line interface
- Michael Twomey, for HTTP proxy support
- Mark Recht, for patches to support SOAPpy

Classes
`SearchResult` | Encapsulates the results from a search.
`SearchResultsMetaData` | Container class for metadata about a given search query's results.
`SearchReturnValue` | complete search results for a single query
`_OutputFormatter` |
`_SearchBase` |
`_TextOutputFormatter` |

Exceptions
`NoLicenseKey` | Thrown when the API is unable to find a valid license key.

Function Summary
String | ``doGetCachedPage`(url, license_key, http_proxy)` Retrieve a page from the Google cache.
`SearchReturnValue` | ``doGoogleSearch`(q, start, maxResults, filter, restrict, safeSearch, language, inputencoding, outputencoding, license_key, http_proxy)` Search Google using the SOAP API and return the results.
| ``doSpellingSuggestion`(phrase, license_key, http_proxy)` Get spelling suggestions from Google
String | ``getLicense`(license_key)` Get the Google APIs license key
String | ``getProxy`(http_proxy)` Get the HTTP proxy we use for accessing Google
| ``main`(argv)` Command-line interface.
| ``setLicense`(license_key)` Set the Google APIs license key
| ``setProxy`(http_proxy)` Set the HTTP proxy to be used when accessing Google
| `_contentsOf(dirname, filename)`
| `_getRemoteServer(http_proxy)`
| `_getScriptDir()`
| `_makeFormatter(outputFormat)`
| `_marshalBoolean(value)`
| `_output(results, params)`
| ``_test`()` Run functional test suite.
| ``_usage`()` Display usage information for the command-line interface
| ``_version`()` Display a formatted version string for the module

Variable Summary
`str` | `__author__` = `'Mark Pilgrim (f8dy@diveintomark.org)'`
`str` | `__copyright__` = `'Copyright (c) 2002 Mark Pilgrim'`
`str` | `__credits__` = `'David Ascher, for the install script\nEri...`
`str` | `__cvsversion__` = `'1.5'`
`str` | `__date__` = `'2004/02/25 23:46:07'`
`str` | `__license__` = `'Python'`
`str` | `__version__` = `'0.6'`
`NoneType` | `HTTP_PROXY` = None
`NoneType` | `LICENSE_KEY` = None
`booleanType` | `_false` = `<SOAPpy.Types.booleanType at 4590488>`
`str` | `_googlefile1` = `'.googlekey'`
`str` | `_googlefile2` = `'googlekey.txt'`
`tuple` | `_licenseLocations` = `((<function <lambda> at 0x855b0>, 'p...`
`str` | `_namespace` = `'urn:GoogleSearch'`
`booleanType` | `_true` = `<SOAPpy.Types.booleanType at 532192>`
`str` | `_url` = `'http://api.google.com/search/beta2'`

Function Details

### doGetCachedPage(url, license_key=None, http_proxy=None)

Retrieve a page from the Google cache.

You need a license key to call this function; see the Google APIs site to get one. Then you can either pass it to this function every time, or set it globally; see the `google` module-level docs for details.

  Parameters:
    `url` - full URL to the page to retrieve
    (type=String)
    `license_key` - (optional) the Google API key to use
    (type=String)
    `http_proxy` - (optional) the HTTP proxy server to use
    (type=String)
  Returns:
    full text of the cached page
    (type=String)

### doGoogleSearch(q, start=0, maxResults=10, filter=1, restrict='', safeSearch=0, language='', inputencoding='', outputencoding='', license_key=None, http_proxy=None)

Search Google using the SOAP API and return the results.

You need a license key to call this function; see the Google APIs site to get one. Then you can either pass it to this function every time, or set it globally; see the `google` module-level docs for details.

See http://www.google.com/help/features.html for examples of advanced features. Anything that works at the Google web site will work as a query string in this method.

You can use the `start` and `maxResults` parameters to page through multiple pages of results. Note that 'maxResults' is currently limited by Google to 10.

See the API reference for more advanced examples and a full list of country codes and topics for use in the `restrict` parameter, along with legal values for the `language`, `inputencoding`, and `outputencoding` parameters.

You can download the API documentation http://www.google.com/apis/download.html.

  Parameters:
    `q` - search string.
    (type=String)
    `start` - (optional) zero-based index of first desired result.
    (type=int)
    `maxResults` - (optional) maximum number of results to return.
    (type=int)
    `filter` - (optional) flag to request filtering of similar results
    (type=int)
    `restrict` - (optional) restrict results by country or topic.
    (type=String)
    `safeSearch` - (optional)
    (type=int)
    `language` - (optional)
    (type=String)
    `inputencoding` - (optional)
    (type=String)
    `outputencoding` - (optional)
    (type=String)
    `license_key` - (optional) the Google API license key to use
    (type=String)
    `http_proxy` - (optional) the HTTP proxy to use for talking to Google
    (type=String)
  Returns:
    the search results encapsulated in an object
    (type=`SearchReturnValue`)

### doSpellingSuggestion(phrase, license_key=None, http_proxy=None)

Get spelling suggestions from Google

You need a license key to call this function; see the Google APIs site to get one. Then you can either pass it to this function every time, or set it globally; see the `google` module-level docs for details.

  Parameters:
    `phrase` - word or phrase to spell-check
    (type=String)
    `license_key` - (optional) the Google API key to use
    (type=String)
    `http_proxy` - (optional) the HTTP proxy to use
    (type=String)
  Returns:
    text of any suggested replacement, or None

### getLicense(license_key=None)

Get the Google APIs license key

The key can be read from any number of locations. See the module-leve documentation for the search order.

  Returns:
    the license key
    (type=String)
  Raises:
    `NoLicenseKey` - if no valid key could be found

### getProxy(http_proxy=None)

Get the HTTP proxy we use for accessing Google

  Returns:
    the proxy
    (type=String)

### main(argv)

Command-line interface.

### setLicense(license_key)

Set the Google APIs license key

  Parameters:
    `license_key` - The new key to use
    (type=String)

  To Do: validate the key?

### setProxy(http_proxy)

Set the HTTP proxy to be used when accessing Google

  Parameters:
    `http_proxy` - the proxy to use
    (type=String)

  To Do: validiate the input?

### _test()

Run functional test suite.

### _usage()

Display usage information for the command-line interface

### _version()

Display a formatted version string for the module

Variable Details

### __author__

  Type:
    `str`
  Value:

        'Mark Pilgrim (f8dy@diveintomark.org)'

### __copyright__

  Type:
    `str`
  Value:

        'Copyright (c) 2002 Mark Pilgrim'

### __credits__

  Type:
    `str`
  Value:

        '''David Ascher, for the install script
        Erik Max Francis, for the command line interface
        Michael Twomey, for HTTP proxy support'''

### __cvsversion__

  Type:
    `str`
  Value:

        '1.5'

### __date__

  Type:
    `str`
  Value:

        '2004/02/25 23:46:07'

### __license__

  Type:
    `str`
  Value:

        'Python'

### __version__

  Type:
    `str`
  Value:

        '0.6'

### HTTP_PROXY

  Type:
    `NoneType`
  Value:

        None

### LICENSE_KEY

  Type:
    `NoneType`
  Value:

        None

### _false

  Type:
    `booleanType`
  Value:

        <SOAPpy.Types.booleanType at 4590488>

### _googlefile1

  Type:
    `str`
  Value:

        '.googlekey'

### _googlefile2

  Type:
    `str`
  Value:

        'googlekey.txt'

### _licenseLocations

  Type:
    `tuple`
  Value:

        ((<function <lambda> at 0x855b0>,
          'passed to the function in license_key variable'),
         (<function <lambda> at 0x4868f0>,
          'module-level LICENSE_KEY variable (call setLicense to set it)'),
         (<function <lambda> at 0x486bb0>,
          'an environment variable called GOOGLE_LICENSE_KEY'),
         (<function <lambda> at 0x48e870>, '.googlekey in the current director\
        y'),
        ...

### _namespace

  Type:
    `str`
  Value:

        'urn:GoogleSearch'

### _true

  Type:
    `booleanType`
  Value:

        <SOAPpy.Types.booleanType at 532192>

### _url

  Type:
    `str`
  Value:

        'http://api.google.com/search/beta2'

Generated by Epydoc 2.0 on Wed Feb 25 18:54:21 2004 | http://epydoc.sf.net