GitHub API Rate Limit Explained

ratelimit_explained.py

from datetime import datetime
from github3 import GitHub


def search_ratelimit(github):
    """Return information about search rate limit."""

    ratelimit = github.rate_limit()
    # `ratelimit` holds the JSON as described here:
    # https://developer.github.com/v3/rate_limit/#get-your-current-rate-limit-status
    # {
    #     "resources": {
    #         "core": {
    #             "limit": 5000,
    #             "remaining": 4999,
    #             "reset": 1372700873
    #         },
    #             "search": {
    #             "limit": 30,
    #             "remaining": 18,
    #             "reset": 1372697452
    #         }
    #     },
    #     "rate": {
    #         "limit": 5000,
    #         "remaining": 4999,
    #         "reset": 1372700873
    #     }
    # }

    # From that dict, get 'resources'
    ratelimit_resources = ratelimit.get('resources', {})

    # `ratelimit_resources` is another dict.
    # Get the element indexed with 'search'
    ratelimit_search = ratelimit_resources.get('search', {})

    # `ratelimit_search` is a dict with the following keys:

    #    - 'limit': How many you get at most.
    limit = ratelimit_search.get('limit', -1)

    #    - 'remaining': How many are left until 'reset'
    remaining = ratelimit_search.get('remaining', -1)

    #    - 'reset': When 'remaining' is set back to 'limit'.
    #               This is a POSIX timestamp.
    #               You can parse it with `datetime`
    reset = datetime.fromtimestamp(ratelimit_search.get('reset'))

    return limit, remaining, reset


# This is unauthenticated. Authenticated rate limits are higher.
github = GitHub()

# A random search:
search_iterator = github.search_repositories('created:2018-01-10 foo')

# Iterate over search results and have an eye on rate limit
for n, search_result in enumerate(search_iterator):
    print('Result {}: {}'.format(n, search_result.repository.full_name))

    # Get current rate limit
    limit, remaining, reset = search_ratelimit(github)

    # Get current time
    now = datetime.now()

    difference = reset - now

    print('Ratelimit remaining: {} of {}.'.format(remaining, limit))
    print('Reset in {} at {})'.format(difference, reset))
    print('Current time: {}'.format(now))

    print('- - - - >8 - - - -')

    if n >= 10:
        print('Manually stop after result {}.'.format(n))
        break

print('''
    NOTICE: Not every search result lowers the remaining rate limit!.
            The rate limit counts _requests_. Each request gives you
            one hundred (100) results on one page.
            The 'SearchIterator' abstracts from that and hands you one
            search result after the other.
    ''')