This is a(nother) Python wrapper for the Stack Exchange API. I wrote this to assist with a couple of my projects that needed to do a lot of API interactions. After using it and polishing it up for as long as I have, it's time to release it for others as well.
Features
- Multiple pages of results are all returned in a single object. The library automatically paginates for you, up to a maximium number of pages the developer selects.
- StackAPI automatically respects the
backoffparameter. This is useful if you are retreiving a large number of pages, as it will automatically slow down to respect the API's backoff. - Supports both read and write functionality, assuming you have an application and token with a scope that contains
write_access. - Errors thrown by the API are automatically converted to Python exceptions for easier troubleshooting
- Support for Python 2.7 through 3.5.
- Supports passing Python
datetimeobjects as parameters to the API. - Supports usage behind a proxy
Installation
Installation is simple:
pip install stackapi
Examples
Basic Example
StackAPI is fairly easy to utilize. You can retrieve the 600 newest comments on a site in three lines of code - including imports.
from stackapi import StackAPI
SITE = StackAPI('stackoverflow')
comments = SITE.fetch('comments')
Filtering API results
If you want to utilize the filters provided by the API, that is as simple as passing data to named parameters. In the following example, we are looking for 3 badges (only 2 of which exist):
from stackapi import StackAPI
SITE = StackAPI('stackoverflow')
badges = SITE.fetch('badges', ids=[222, 1306, 99999])
This will return a result that contains information for badge id 222 and 1306. The third will have no data, as it doesn't exist in the system.
Complex API queries
StackAPI can perform the complex queries mentioned in the documentation. This example shows the questions created during the Modern Warfare 3 VS Skyrim Contest with the skryim tag and a score greater than 10 on Gaming Stack Exchange.
SITE = StackAPI('gaming')
from datetime import datetime
questions = SITE.fetch('questions', fromdate=datetime(2011,11,11), todate=datetime(2011,11,19), min=10, sort='votes', tagged='skyrim')
This will return 231 questions. Notice that we are able to pass in datetime objects, instead of timestamp integers.
Documentation
The Documentation is available on Read The Docs: http://stackapi.readthedocs.org/en/latest/index.html
The documentation contains many more examples of various ways to use StackAPI, including using a proxy, sending data to the API and all of the complex queries mentioned in the API documentation. There is also a full overview of the classes and methods that StackAPI utilizes.
Code
The code is available on GitHub: https://github.com/AWegnerGitHub/stackapi
StackAPI is also available on PyPI: https://pypi.python.org/pypi/StackAPI
License
StackAPI is licensed under the MIT License and that is available in the code repository
