Quickstart¶
Ready to start talking to the Stack Exchange API? This page gives an introduction on how to get started with StackAPI.
First, you need to:
- Install StackAPI
Basic Data Retrieval¶
Retrieving data is very simple.
First, import the StackAPI module:
>>> from stackapi import StackAPI
Now we want to retrieve the most recent comments from Stack Overflow:
>>> SITE = StackAPI('stackoverflow')
>>> comments = SITE.fetch('comments')
This will return the 500 most recent comments on Stack Overflow, using the
default filter the API provides. The value passed to
fetch
is an end point defined in the
Stack Exchange API.
If you are looking for more information on how to tailor the results of your queries. Take a look at the Advanced Usage examples.
Change number of results¶
By default, StackAPI will return up to 500 items in a single call. It may be less than this, if there are less than 500 items to return. This is common on new or low traffic sites.
The number of results can be modified by changing the page_size
and max_pages
values. These are multiplied together to get the maximum
total number of results. The API paginates the results and StackAPI recombines
those pages into a single result.
The number of API calls that are made is dependant on the max_pages
value.
This will be the maximum number of calls that is made for this particular
request.
All of these changes to page_size
and max_pages
need to occur before
calls to fetch
or send_data
.
Let’s walk through a few examples:
>>> SITE.page_size = 10
>>> SITE.max_pages = 10
This will return up to 100 results. However, it will hit the API up to 10 times.
>>> SITE.page_size = 100
>>> SITE.max_pages = 1
This will result up to 100 results as well, but it will only hit the API one time.
Stack Exchange limits the number of results per page to 100. If you want more
than 100 results, you need to increase the max_pages
.
>>> SITE.page_size = 100
>>> SITE.max_pages = 2
This will return up to 200 results and hit the API up to twice.
Getting exact number of results¶
If you want a specific number of results, but no more than that, you need to perform some manipulations of these two values.
>>> SITE.page_size = 50
>>> SITE.max_pages = 3
This will return up to 150 results. It will also hit the API 3 times to get these results. You can save an API hit by changing the values to:
>>> SITE.page_size = 75
>>> SITE.max_pages = 2
This will also return up to 150 results, but do so in only 2 API hits.
Note: Each “page” in an API call can have up to 100 results. In the first
scenario, above, we are “wasting” 150 results because we only allow each page
50 results. In the second scenario, we are wasting 50 results. If you do not
need an exact number of results, it is more efficient - API quota-wise - to set
the page_size
to 100 and return the highest number of results per page that
the system allows.
Errors¶
StackAPI will throw an error if the Stack Exchange API returns an error. This
can be caught in an exception block by catching stackapi.StackAPIError
.
The exception has several values available to help troubleshoot the underlying
issue:
except stackapi.StackAPIError as e:
print(" Error URL: {}".format(e.url))
print(" Error Code: {}".format(e.code))
print(" Error Error: {}".format(e.error))
print(" Error Message: {}".format(e.message))
This will print out the URL that was being accessed, the error number that the API returns, the error code the API returns and the error message the API returns. Using these values, it should be possible to determine the cause of the error. The error code, message and number are all available in the documentation.
Note about Quotas¶
Stack Exchange attempts to prevent abuse of their API by implementing a number
of throttles. The quote values
that you have remaining are returned with more filters that StackAPI utilizes.
These appear as quota_remaining
and quota_max
values.
In some instances though (for example when using a filter='total'
), these
are not part of the Stack Exchange response. In these instances, StackAPI will
set the values to -1
. This is to make it clear that StackAPI does not know
the values and not provide you with an incorrect, positive, value.
To get accurate values for these two fields, you need to ensure that your
filters contain quota_remaining
and quota_max
.