StackAPI Classes and Methods

This portion of the documentation covers all the interfaces of StackAPI.

StackAPI

class stackapi.StackAPI(name=None, version='2.2', **kwargs)
__init__(name=None, version='2.2', **kwargs)

The object used to interact with the Stack Exchange API

Parameters:
  • name – (string) (Required) A valid api_site_parameter (available from http://api.stackexchange.com/docs/sites) which will be used to connect to a particular site on the Stack Exchange Network.
  • version – (float) (Required) The version of the API you are connecting to. The default of 2.2 is the current version
  • proxy –

    (dict) (optional) A dictionary of http and https proxy locations Example:

    {'http': 'http://example.com',
 'https': 'https://example.com'}

    By default, this is None.

  • max_pages – (int) (optional) The maximum number of pages to retrieve (Default: 100)
  • page_size – (int) (optional) The number of elements per page. The API limits this to a maximum of 100 items on all end points except site
  • key – (string) (optional) An API key
  • access_token – (string) (optional) An access token associated with an application and a user, to grant more permissions (such as write access)
__repr__() <==> repr(x)
fetch(endpoint=None, page=1, key=None, filter='default', **kwargs)

Returns the results of an API call.

This is the main work horse of the class. It builds the API query string and sends the request to Stack Exchange. If there are multiple pages of results, and we’ve configured max_pages to be greater than 1, it will automatically paginate through the results and return a single object.

Returned data will appear in the items key of the resulting dictionary.

Parameters:
  • endpoint –

    (string) The API end point being called. Available endpoints are listed on the official API documentation: http://api.stackexchange.com/docs

    This can be as simple as fetch('answers'), to call the answers end point

    If calling an end point that takes additional parameter, such as id`s pass the ids as a list to the `ids key:

    fetch('answers/{}', ids=[1,2,3])

    This will attempt to retrieve the answers for the three listed ids.

    If no end point is passed, a ValueError will be raised

  • page – (int) The page in the results to start at. By default, it will start on the first page and automatically paginate until the result set reached max_pages.
  • key – (string) The site you are issuing queries to.
  • filter – (string) The filter to utilize when calling an endpoint. Different filters will return different keys. The default is default and this will still vary depending on what the API returns as default for a particular endpoint
  • kwargs – Parameters accepted by individual endpoints. These parameters must be named the same as described in the endpoint documentation
Return type:

(dictionary) A dictionary containing wrapper data regarding the API call and the results of the call in the items key. If multiple pages were received, all of the results will appear in the items tag.
send_data(endpoint=None, page=1, key=None, filter='default', **kwargs)

Sends data to the API.

This call is similar to fetch, but sends data to the API instead of retrieving it.

Returned data will appear in the items key of the resulting dictionary.

Sending data requires that the access_token is set. This is enforced on the API side, not within this library.

Parameters:
  • endpoint –

    (string) The API end point being called. Available endpoints are listed on the official API documentation: http://api.stackexchange.com/docs

    This can be as simple as fetch('answers'), to call the answers end point

    If calling an end point that takes additional parameter, such as id`s pass the ids as a list to the `ids key:

    fetch('answers/{}', ids=[1,2,3])

    This will attempt to retrieve the answers for the three listed ids.

    If no end point is passed, a ValueError will be raised

  • page – (int) The page in the results to start at. By default, it will start on the first page and automatically paginate until the result set reached max_pages.
  • key – (string) The site you are issuing queries to.
  • filter – (string) The filter to utilize when calling an endpoint. Different filters will return different keys. The default is default and this will still vary depending on what the API returns as default for a particular endpoint
  • kwargs – Parameters accepted by individual endpoints. These parameters must be named the same as described in the endpoint documentation
Return type:

(dictionary) A dictionary containing wrapper data regarding the API call and the results of the call in the items key. If multiple pages were received, all of the results will appear in the items tag.

StackAPIError

class stackapi.StackAPIError(url, error, code, message)

The Exception that is thrown when ever there is an API error.

This utilizes the values returned by the API and described here: http://api.stackexchange.com/docs/types/error

Parameters:
  • url – (string) The URL that was called and generated an error
  • error – (int) The error_id returned by the API (should be an int)
  • code – (string) The description returned by the API and is human friendly
  • message – (string) The error_name returned by the API
__init__(url, error, code, message)

x.__init__(…) initializes x; see help(type(x)) for signature