API Documentation¶

Blacklist¶

GET /v2/client/blacklist¶
Displays current blacklist associated with client key

Note

Blacklist is cached for 10 minutes. If you recently made changes they will appear here within 10 minutes.

Request:
GET https://api.thenounproject.com/v2/client/blacklist
Response:
{
  "blacklist": {
    "collection_ids": [
      1234
    ],
    "icon_ids": [
      42,
      143,
      1337
    ],
    "search_terms": [
      "bad word here",
      "harry potter",
      "previous blacklist entry here",
      "ünîcōdę is šüppørtëd, along with phråses"
    ]
  },
  "usage_limits": {
    "monthly": {
      "limit": 5000,
      "usage": 440
    }
  }
}
POST /v2/client/blacklist/id¶
Accepts array of blacklist ids

Query Parameters

type (string) – the blacklist type, values must be either “icon” or “collection” and is set to “icon” by default.

Parameters

json (json) – should include “blacklist” which is an array of icon ids or collection ids, and optionally “overwrite” which overwrites the old blacklist if true, and adds to it if false.

Important

Maximum array length of 1,000 per request (5 for free users)

Maximum icon & collection id blacklist length of 20,000 total (5 for free users)

Request:
POST https://api.thenounproject.com/v2/client/blacklist/id?type=icon
Data:
{
  "blacklist": [
    42,
    1337
  ],
  "overwrite": false
}
Response:
{
  "blacklist": {
    "collection_ids": [
      1234
    ],
    "icon_ids": [
      42,
      143,
      1337
    ],
    "search_terms": [
      "bad word here",
      "harry potter",
      "previous blacklist entry here",
      "ünîcōdę is šüppørtëd, along with phråses"
    ]
  },
  "usage_limits": {
    "monthly": {
      "limit": 5000,
      "usage": 440
    }
  }
}
POST /v2/client/blacklist/term¶
Accepts array of blacklist terms and phrases

Parameters

json (json) – should include “blacklist” which is an array of terms and phrases, and optionally “overwrite” which overwrites the old blacklist if true, and adds to it if false.

Important

Maximum array length of 1,000 per request (5 for free users)

Maximum search term blacklist length of 20,000 total (5 for free users)

Request:
POST https://api.thenounproject.com/v2/client/blacklist/term
Data:
{
  "blacklist": [
    "harry potter",
    "ünîcōdę is šüppørtëd, along with phråses"
  ],
  "overwrite": false
}
Response:
{
  "blacklist": {
    "collection_ids": [
      1234
    ],
    "icon_ids": [
      42,
      143,
      1337
    ],
    "search_terms": [
      "bad word here",
      "harry potter",
      "previous blacklist entry here",
      "ünîcōdę is šüppørtëd, along with phråses"
    ]
  },
  "usage_limits": {
    "monthly": {
      "limit": 5000,
      "usage": 440
    }
  }
}

Reporting¶

POST /v2/client/report¶
Accepts array of icon ids for reporting icon usage

Parameters

json (json) – should include “icons” which is an array of icon ids, and optionally “test” which if true will not record the data supplied.

Important

Max array length of 1,000 per request

Request:
POST https://api.thenounproject.com/v2/client/report
Data:
{
  "icons": [
    42,
    143,
    1337
  ],
  "test": true
}
Response:
{
  "message": "You are in test mode.",
  "test": true,
  "total_icons_reported": 3,
  "usage_limits": {
    "monthly": {
      "limit": 5000,
      "usage": 440
    }
  }
}

Usage¶

GET /v2/client/usage¶
Returns current client key usage and limits

Request:
GET https://api.thenounproject.com/v2/client/usage
Response:
{
  "monthly": {
    "limit": 5000,
    "usage": 440
  }
}

Icon¶

GET /v2/icon/(int: icon_id)¶

Returns a single icon

Parameters

icon_id (int) – icon id

Query Parameters

thumbnail_size (int) – the thumbnail size to be returned (42, 84, 200)
blacklist (int) – removes any results matching terms or ids in blacklist

Note

Asset URLs are temporary and will expire within an hour after the call. Following that duration, a new call will be required to retrieve a new asset URL.

Request:

GET https://api.thenounproject.com/v2/icon/1234?thumbnail_size=200

Response:

{
  "generated_at": "2018-05-10 00:26:42.221427",
  "icon": {
    "attribution": "Telephone by John Caserta from Noun Project",
    "collections": [
      {
        "creator": {
          "name": "John Caserta",
          "permalink": "/johncaserta",
          "username": "johncaserta"
        },
        "id": "5",
        "name": "Modern Pictograms",
        "permalink": "/johncaserta/collection/modern-pictograms"
      }
    ],
    "creator": {
      "name": "John Caserta",
      "permalink": "/johncaserta",
      "username": "johncaserta"
    },
    "icon_url": "https://static.thenounproject.com/svg_clean/1234.svg?Expires=1525915602&Signature=ZtepAdnb-RJ-nkKsy3P0f-4rz9zvE59F5z1tDUIOCo6frgKlw7q739zelNpNCgfPnQ4mQzTK1OG9x6DJaC8fkQRLu2zjK3IHQ4NO1sRNW8ZkrRTdM~gXXX2ZGmmOEc7QUPoUGdDd0iZO93CZPFUG-TQ3U2cdLMsS0z6EZuw~LLo_&Key-Pair-Id=APKAI5ZVHAXN65CHVU2Q",
    "id": "1234",
    "license_description": "creative-commons-attribution",
    "permalink": "/term/telephone/1234",
    "tags": [
      "telephone",
      "communication",
      "phone",
      "talking",
      "tech",
      "technology"
    ],
    "term": "Telephone",
    "thumbnail_url": "https://static.thenounproject.com/png/1234-200.png"
  },
  "total": 1,
  "usage_limits": {
    "monthly": {
      "limit": 5000,
      "usage": 440
    }
  }
}

GET /v2/icon/(int: icon_id)/download¶

Returns a single icon file of desired color and filetype

Parameters

icon_id (int) – icon id

Query Parameters

color (string) – hexadecimal color value
filetype (string) – svg or png filetype
size (int) – size of png (minimum of 20, maximum of 1200)

Note

filetype svg does not accept a size
free api access is limited to public domain icons
paid api access will allow you to edit any icon

Request:

GET https://api.thenounproject.com/v2/icon/1/download?color=A3A3A3&filetype=png&size=25

Response:

{
  "base64_encoded_file": "iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAEiUlEQVR4nJ1VS4gcZRD+6v/7MdOz47KJBBmIEcKuYkRUIl6UTAeUECSisoOS2UQRWU/G+ACNYG978OJFT5KwGubFwigeFrwEdAZPgZgImx1FEwgxgQjDZJiVeXRP919eutfZh0k2dfopqur7qqrra8JdGDMLIlLlcvktTdM+B+APh8PZmZmZ76rVqszlcuFoPN0FABERnz59+j5N0y5LKVNSSvi+f218fPyhQ4cO9ZkZRMRxjtgqyNzcHAGAruumlDJFRCAiANjWarUMZt6Qs+VOAKBWq2m2bQfFYvG4aZonAAw9z/vgyJEjFWYmAGs62TKI4zjCdV1VLpd3WZa1s9/vPxyG4TCRSFwiIrp58+bZ2dnZYVSbtwwSL7VQKLxkWVaBiMY8zwMRQdd1AIDv+xeUUs/n8/m/446027HOZrMCAJrNpmg0GsHCwsJOZv4mDMMx3/cDIpIAEAQBA8D27dufaLfb7xPRe7VaTQMQ3BLEdV3luq4a9ZXL5flUKjW+srLCQojVfCEEKaXavV5vnJmnImIMAJuCxJ9pqVR6MJlM7u/1ehIAE9FUOp1+rtPpXJBSdk3TfGYwGCgA0DRNDIfDb/v9/ptSyjX1NgWp1+uyWq2y7/tOJpN5tdPpQAgBZsbKygo0TXs9DMMTUkpwxCgixzHJ24LYth0AQLFYfOf69es/+r4PpRTGxsZEv9+/cvTo0aVSqbRNKbVZ+gbbAOI4jshkMjKdTn/KzMu5XO7rzWIAhOv9dwTiOI6WyWRoYmLCGg6HbyilzgCoVKtVo91u89TUlFxaWuJjx455pVIpPrb1Jx4CWNPiGhDXdYPo2SkWi48IIV4rFosvT09Pfx9d8HA0npkhpdRiKSEilUwmtX6/nxyNEyPto1KpvFIul98GgEQi8Q+Aj4joXQBUqVQmFxcXPykUCvfHybquIwzD35RSN5LJJAD86XnexwC+AIBGo8GrIPHBKaX2GYbx5cmTJ61cLtcfDAZ7LMt6kYhUGIYvaJrmSiljbVKmaQLAWSHEVcMwoJQKDx8+/NnMzMwP0WTUKki9Xo/JnTEMI7Qsa1ulUtm3Y8eOn3q93r1R0b3NZvNGPp+/Go2KI0k3mVmP3uQ4jra8vGxsGFe8KCHE7wAkMz/OzB0A14QQ8R72Sikvjq5kJHd1+a7rBs1mc+Pi5+bm2HVdTExMXGm1Wr4QYn8+nz8O4FkAmJ+fTwshHlBKLWCdRR2sd68xEY2CHccRBw8e9Jj5D2beC4BqtVoCAJmmOZlKpSQR/bK+wOh/45YgwH/LJ6LzzPxotVoV9Xrdj0bxWBiGIKKL/1fojkBG7JxlWfd0u92d2WxWRHL9VK/X62Yymb/W69KWQGJZFkL8ahgGhBC7bNsObNsOmPlJAA3btoNTp07FBxwvV8XC+H+jW7346elpBQC6rl/udrsDKeWHpVLpaWYmwzD2BEHwFQAMBoOYmCGEABHpAPRIpTcV3FVnzKLRaLR27959KZ1OH1BKHWBmCCE4CILzADA5ORmn/KyUygohFsMwXPE8b0pKeW50KrH9CxPIMKj1/EicAAAAAElFTkSuQmCC",
  "content_type": "image/png",
  "usage_limits": {
    "monthly": {
      "limit": 5000,
      "usage": 183
    }
  }
}

GET /v2/icon¶

Returns a list of icons

Query Parameters

query (string) – search term
limit_to_public_domain (int) – limit results to public domain icons only
thumbnail_size (int) – the thumbnail size to be returned (42, 84, 200)
blacklist (int) – removes any results matching terms or ids in blacklist
include_svg (int) – include svgs in the results
limit (int) – maximum number of results
prev_page (string) – token for paging to the previous page
next_page (string) – token for paging to the next page

Important

By default, PNG urls are included. SVG sizes vary from a few hundred bytes to several megabytes. We recommend using PNGs for displaying large numbers of icons at once, and retrieving the SVG for a specific icon when a vector format is needed.

Note

Asset URLs are temporary and will expire within an hour after the call. Following that duration, a new call will be required to retrieve a new asset URL.

Request:

GET https://api.thenounproject.com/v2/icon?query=parking&limit=4&thumbnail_size=84&blacklist=1&next_page=31352E3739393633322C69636F6E2331333534303034

Response:

{
  "generated_at": "2018-05-15 20:14:50.615761",
  "icons": [
    {
      "attribution": "Parking by I Like Bears from Noun Project",
      "collections": [
        {
          "creator": {
            "name": "I Like Bears",
            "permalink": "/ilkebrs",
            "username": "ilkebrs"
          },
          "id": "4459",
          "name": "Estate Amenities",
          "permalink": "/ilkebrs/collection/estate-amenities"
        }
      ],
      "creator": {
        "name": "I Like Bears",
        "permalink": "/ilkebrs",
        "username": "ilkebrs"
      },
      "id": "148533",
      "license_description": "creative-commons-attribution",
      "permalink": "/term/parking/148533",
      "tags": [
        "parking",
        "automobile",
        "car",
        "taxi",
        "transport",
        "transportation",
        "travel"
      ],
      "term": "Parking",
      "thumbnail_url": "https://static.thenounproject.com/png/148533-84.png"
    },
    {
      "attribution": "Parking Sign by Vectors Market from Noun Project",
      "collections": [
        {
          "creator": {
            "name": "Vectors Market",
            "permalink": "/vectorsmarket",
            "username": "vectorsmarket"
          },
          "id": "37560",
          "name": "Parking Line Icon",
          "permalink": "/vectorsmarket/collection/parking-line-icon"
        }
      ],
      "creator": {
        "name": "Vectors Market",
        "permalink": "/vectorsmarket",
        "username": "vectorsmarket"
      },
      "id": "1204672",
      "license_description": "creative-commons-attribution",
      "permalink": "/term/parking-sign/1204672",
      "tags": [
        "parking-sign",
        "parking",
        "parking-area",
        "parking-space",
        "parking-zone"
      ],
      "term": "Parking Sign",
      "thumbnail_url": "https://static.thenounproject.com/png/1204672-84.png"
    },
    {
      "attribution": "car parking by SBTS from Noun Project",
      "collections": [
        {
          "creator": {
            "name": "SBTS",
            "permalink": "/sbts2018",
            "username": "sbts2018"
          },
          "id": "50788",
          "name": "Car set1",
          "permalink": "/sbts2018/collection/car-set1"
        }
      ],
      "creator": {
        "name": "SBTS",
        "permalink": "/sbts2018",
        "username": "sbts2018"
      },
      "id": "1694509",
      "license_description": "creative-commons-attribution",
      "permalink": "/term/car-parking/1694509",
      "tags": [
        "car-parking",
        "no-parking",
        "parking-lot",
        "parking-sign",
        "vehicle-parking"
      ],
      "term": "car parking",
      "thumbnail_url": "https://static.thenounproject.com/png/1694509-84.png"
    },
    {
      "attribution": "Parking by Pause08 from Noun Project",
      "collections": [
        {
          "creator": {
            "name": "Pause08",
            "permalink": "/Pause08",
            "username": "Pause08"
          },
          "id": "45832",
          "name": "Hotel Collection",
          "permalink": "/Pause08/collection/hotel-collection"
        }
      ],
      "creator": {
        "name": "Pause08",
        "permalink": "/Pause08",
        "username": "Pause08"
      },
      "id": "1541332",
      "license_description": "creative-commons-attribution",
      "permalink": "/term/parking/1541332",
      "tags": [
        "parking",
        "car-parking",
        "hotel",
        "service",
        "travel"
      ],
      "term": "Parking",
      "thumbnail_url": "https://static.thenounproject.com/png/1541332-84.png"
    }
  ],
  "next_page": "31332E3932333137352C69636F6E2331353431333332",
  "prev_page": "31352E3635353936352C69636F6E23313438353333",
  "total": 1009,
  "usage_limits": {
    "monthly": {
      "limit": 5000,
      "usage": 440
    }
  }
}

Collection¶

GET /v2/collection¶

Returns a list of collections

Query Parameters

query (string) – search term
blacklist (int) – removes any results matching terms or ids in blacklist
limit (int) – maximum number of results
prev_page (string) – token for paging to the previous page
next_page (string) – token for paging to the next page

Request:

GET https://api.thenounproject.com/v2/collection?query=winter&limit=3&blacklist=1

Response:

{
  "collections": [
    {
      "creator": {
        "name": "Tamiko Young",
        "permalink": "/tamikoy1",
        "username": "tamikoy1"
      },
      "icon_count": 15,
      "id": "56",
      "name": "Winter Olympicons",
      "permalink": "/tamikoy1/collection/winter-olympicons",
      "tags": [
        "athlete",
        "sport",
        "olympics",
        "sports",
        "winter"
      ]
    },
    {
      "creator": {
        "name": "Matt Brooks",
        "permalink": "/Mattebrooks",
        "username": "Mattebrooks"
      },
      "icon_count": 24,
      "id": "155",
      "name": "Christmas Icons",
      "permalink": "/Mattebrooks/collection/christmas-icons",
      "tags": [
        "snow",
        "winter",
        "vacation",
        "christmas",
        "holiday"
      ]
    },
    {
      "creator": {
        "name": "Factorio.us collective",
        "permalink": "/factorious",
        "username": "factorious"
      },
      "icon_count": 16,
      "id": "51",
      "name": "Xmas Icons",
      "permalink": "/factorious/collection/xmas-icons",
      "tags": [
        "christmas",
        "holiday",
        "winter",
        "decoration",
        "celebrate"
      ]
    }
  ],
  "generated_at": "2023-11-16 23:22:43.311288",
  "total": 3,
  "usage_limits": {
    "monthly": {
      "limit": 5000,
      "usage": 385
    }
  }
}

GET /v2/collection/(int: collection_id)¶

Returns a single collection

Parameters

collection_id (int) – collection id

Query Parameters

blacklist (int) – removes any results matching terms or ids in blacklist
thumbnail_size (int) – the thumbnail size to be returned (42, 84, 200)
include_svg (int) – include svgs in the results
limit (int) – maximum number of icon results
prev_page (string) – token for paging to the previous page of icons
next_page (string) – token for paging to the next page of icons

Request:

GET https://api.thenounproject.com/v2/collection/10/?thumbnail_size=42&limit=2&blacklist=1

Response:

{
  "collection": {
    "creator": {
      "name": "Adam Whitcroft",
      "permalink": "/adamwhitcroft",
      "username": "adamwhitcroft"
    },
    "icon_count": 72,
    "icons": [
      {
        "attribution": "Wind by Adam Whitcroft from Noun Project",
        "collections": [
          {
            "creator": {
              "name": "Adam Whitcroft",
              "permalink": "/adamwhitcroft",
              "username": "adamwhitcroft"
            },
            "id": "10",
            "name": "Climacons",
            "permalink": "/adamwhitcroft/collection/climacons"
          }
        ],
        "creator": {
          "name": "Adam Whitcroft",
          "permalink": "/adamwhitcroft",
          "username": "adamwhitcroft"
        },
        "id": "2708",
        "license_description": "creative-commons-attribution",
        "permalink": "/term/wind/2708",
        "tags": [
          "wind",
          "gale",
          "weather",
          "climacons",
          "gust"
        ],
        "term": "Wind",
        "thumbnail_url": "https://static.test.thenounproject.com/png/2708-42.png"
      },
      {
        "attribution": "Umbrella by Adam Whitcroft from Noun Project",
        "collections": [
          {
            "creator": {
              "name": "Adam Whitcroft",
              "permalink": "/adamwhitcroft",
              "username": "adamwhitcroft"
            },
            "id": "10",
            "name": "Climacons",
            "permalink": "/adamwhitcroft/collection/climacons"
          }
        ],
        "creator": {
          "name": "Adam Whitcroft",
          "permalink": "/adamwhitcroft",
          "username": "adamwhitcroft"
        },
        "id": "2707",
        "license_description": "creative-commons-attribution",
        "permalink": "/term/umbrella/2707",
        "tags": [
          "umbrella",
          "weather",
          "climacons",
          "rain",
          "brolly"
        ],
        "term": "Umbrella",
        "thumbnail_url": "https://static.test.thenounproject.com/png/2707-42.png"
      }
    ],
    "id": "10",
    "name": "Climacons",
    "next_page": "312E302C32373037",
    "permalink": "/adamwhitcroft/collection/climacons",
    "tags": [
      "weather",
      "climacons",
      "cloud",
      "climate",
      "moon"
    ]
  },
  "generated_at": "2024-01-09 11:20:21.886092",
  "total": 1,
  "usage_limits": {
    "monthly": {
      "limit": 5000,
      "usage": 130
    }
  }
}

Autocomplete¶

GET /v2/icon/autocomplete¶
Returns a list of terms

Query Parameters

query (string) – term

blacklist (int) – removes any results matching terms in blacklist

limit (int) – maximum number of results

Note

Maximum limit of 10

Request:
GET https://api.thenounproject.com/v2/icon/autocomplete?query=engine&blacklist=1&limit=5
Response:
{
  "generated_at": "2023-01-31 23:59:49.045512",
  "suggestions": [
    "engine coolant",
    "engine filter",
    "engine valves",
    "engineer",
    "engineering"
  ],
  "usage_limits": {
    "monthly": {
      "limit": 5000,
      "usage": 189
    }
  }
}