Getting Started

TheNounProjectAPI is a Python wrapper allowing convenient access to the Noun Project API. It supports all endpoints and types of responses.

API keys

Before any requests can be made, the api key and secret need to be set. These keys can be generated once you have made a Noun Project account. See this topic on the official Noun Project documentation for more information.

Once you have generated these keys, they need to be set in the api wrapper. This can be done in a few ways. For each of these ways, assume that this section of code is present at the top:

from TheNounProjectAPI import API
key = "<sample api key>"
secret = "<sample secret key>"

You can pass the keys to the constructor when creating the object:

api = API(key=key, secret=secret)

You can also set the attributes directly:

api = API()
api.api_key = key
api.secret_key = secret

Or call the api key and secret key setters:

api = API()
api.set_api_key(key)
api.set_secret_key(secret)

Making requests

Once an API object has been set up, it can be used to make requests. Some of the most useful methods used for these requests are listed here.

Methods	Example output
get_collection()	Collection
get_collection_icons()	Icons
get_collections()	Collections
get_icon()	Icon
get_icons_by_term()	Icons
get_recent_icons()	Icons
get_usage()	Usage
get_user_collection()	Collection
get_user_collections()	Collections
get_user_uploads()	Icons
report_usage()	Enterprise

See API for the other methods not listed here.

See the official Noun Project documentation for more information regarding what information may be fetched.

Output handling

Let’s take a look at some examples of how to parse the outputs from the aforementioned methods.

Icons

# See Sample outputs -> Icons for more information about this:
icons = api.get_icons_by_term("goat", public_domain_only=True, limit=2)

# >>>icons
# [<IconModel: Term: Goat Feeding, Slug: goat-feeding, Id: 24014>,
# <IconModel: Term: Herbivore teeth, Slug: herbivore-teeth, Id: 675870>]

for icon in icons:
    print("Icon's term:", icon.term)
    print("This icon's tags:", ", ".join(tag.slug for tag in icon.tags))
    print("Uploader's username:", icon.uploader.username)

Icon

# See Sample outputs -> Icon for more information about this:
icon = api.get_icon("goat")

# >>>icon
# <IconModel: Term: Goat, Slug: goat, Id: 8786>

print("Icon's term:", icon.term)
print("This icon's tags:", ", ".join(tag.slug for tag in icon.tags))
print("Uploader's username:", icon.uploader.username)

Collections

# See Sample outputs -> Collections for more information about this:
collections = api.get_collections(limit=3)

# >>>collections
# [<CollectionModel: Name: Electric, Slug: electric, Id: 88081>,
#  <CollectionModel: Name: Banking, Slug: banking, Id: 88080>,
#  <CollectionModel: Name: Academy, Slug: academy, Id: 88079>]

for collection in collections:
    print("Collection's name:", collection.name)
    print("Collection's tags:", ", ".join(tag for tag in collection.tags))
    print("Author's username:", collection.author.username)

Collection

# See Sample outputs -> Collection for more information about this:
collection = api.get_collection("goat")

# >>>collection
# <CollectionModel: Name: Goat, Slug: goat, Id: 6861>

print("Collection's name:", collection.name)
print("Collection's tags:", ", ".join(tag for tag in collection.tags))
print("Author's username:", collection.author.username)

Usage

# See Sample outputs -> Usage for more information about this:
usage = api.get_usage()

# >>>usage
# <UsageModel: Hourly: 12, Daily: 12, Monthly: 226>

print("Monthly limit:", usage.limits.monthly)
print("Today's usage:", usage.usage.daily)

Exception handling

This wrapper may raise any exception listed in exceptions. Here’s some clarification regarding some of these exceptions:

Exception	How to handle
APIKeyNotSet	One or both of the keys have not been set correctly. See API keys for how to resolve this exception.
IncorrectType NonPositive IllegalSlug IllegalTerm	One or more of the parameters passed to the method is not correct. See the exception class and program output for more information on how to resolve the exception.
ServerException	The Noun Project API is likely experiencing issues. There is not much you can do about this, except for waiting.
BadRequest NotFound	A page that does not exist has been requested. This can happen for example when asking for an icon, collection or user that does not exist.
Unauthorized	The authentication is incorrect, most likely due to the api key and/or secret being incorrect.
RateLimited	You may have been rate limited. You may have sent too many requests, or you’ve been timed out.
UnknownStatusCode	Any status code without a custom exception has been returned from the API. Please look up the status code in the error message for more information.