===========================
API v1 → v2 Migration Guide
===========================
The following guide will help you migrate from API v1 to API v2.
**Note:** Authentication has not changed. The same request and authentication code used previously to access v1 endpoints will continue to work for accessing v2 endpoints.
Migration checklist for developers
- Familiarize yourself with the new endpoint response structure.
- Check whether you are using deprecated or renamed fields within the new endpoint responses.
- Figure out which v1 endpoints you are currently using and find the equivalent v2 ones in the mapping below.
- Update your code to replace the API v1 calls with calls to API v2, and switch to using the updated fields in the endpoint responses if you are using ones that have been removed or renamed.
Endpoints: v1 → v2 mapping
--------------------------
.. list-table::
:width: 100%
:class: full-width-table
* - **v1 Endpoint**
- **v2 Endpoint**
* - :code:`/icon/{ icon_id }`
- :code:`/v2/icon/{ icon_id }`
* - :code:`/icons/{ search_term }`
- :code:`/v2/icon?query={ search_term }`
* - :code:`/oauth/usage`
- :code:`/v2/oauth/usage`
* - :code:`/notify/publish`
- :code:`/v2/client/report`
Responses: v1 → v2 changes
--------------------------
Request a single icon by id
###########################
:code:`/icon/{ icon_id }` → :code:`/v2/icon/{ icon_id }`
- Renamed PNG thumbnail key from :code:`preview_url` to :code:`thumbnail_url`
- Removed :code:`preview_url_42` and :code:`preview_url_84` - both can now be retrieved by specifying :code:`thumbnail_size={ size }` as a query parameter
- Renamed collections :code:`author` key to :code:`creator`
- Renamed icon :code:`author` key to :code:`creator`
- Simplified icon response
- Simplified icon creator response
- Simplified tags response
- Simplified collections response
- Added monthly API usage data in response
.. raw:: html
v1 Response
.. code-block:: json
{
"icon": {
"attribution": "Trash by AIGA from Noun Project",
"collections": [
{
"author": {
"location": "US",
"name": "AIGA",
"permalink": "/aiga-icons",
"username": "aiga-icons"
},
"author_id": "3805019",
"date_created": "2012-01-27 19:15:26",
"date_updated": "2018-04-17 20:37:44",
"description": "",
"id": "3",
"is_collaborative": "",
"is_featured": "1",
"is_published": "1",
"is_store_item": "0",
"name": "Symbol Signs",
"permalink": "/aiga-icons/collection/symbol-signs",
"slug": "symbol-signs",
"sponsor": {},
"sponsor_campaign_link": "",
"sponsor_id": "",
"tags": [],
"template": "24"
}
],
"date_uploaded": "",
"icon_url": "https://static.thenounproject.com/noun-svg/1.svg",
"id": "1",
"is_active": "1",
"is_explicit": "0",
"license_description": "public-domain",
"nounji_free": "0",
"permalink": "/term/trash/1",
"preview_url": "https://static.thenounproject.com/png/1-200.png",
"preview_url_42": "https://static.thenounproject.com/png/1-42.png",
"preview_url_84": "https://static.thenounproject.com/png/1-84.png",
"sponsor": {},
"sponsor_campaign_link": null,
"sponsor_id": "",
"tags": [
{
"id": 19,
"slug": "trash"
},
{
"id": 20,
"slug": "garbage"
},
{
"id": 1974,
"slug": "trash-can"
},
{
"id": 11120,
"slug": "throw-away"
}
],
"term": "Trash",
"term_id": 19,
"term_slug": "trash",
"updated_at": "2019-04-22 19:22:17",
"uploader": {
"location": "US",
"name": "AIGA",
"permalink": "/aiga-icons",
"username": "aiga-icons"
},
"uploader_id": "3805019",
"year": 1974
}
}
.. raw:: html
v2 Response
.. code-block:: json
{
"generated_at": "2023-03-22 23:04:03.209789",
"icon": {
"attribution": "Trash by AIGA from Noun Project",
"collections": [
{
"creator": {
"name": "AIGA",
"permalink": "/aiga-icons",
"username": "aiga-icons"
},
"id": "3",
"name": "Symbol Signs",
"permalink": "/aiga-icons/collection/symbol-signs"
}
],
"creator": {
"name": "AIGA",
"permalink": "/aiga-icons",
"username": "aiga-icons"
},
"icon_url": "https://static.thenounproject.com/svg_clean/1.svg",
"id": "1",
"license_description": "public-domain",
"permalink": "/term/trash/1",
"tags": [
"trash",
"garbage",
"trash-can",
"throw-away"
],
"term": "Trash",
"thumbnail_url": "https://static.thenounproject.com/png/1-200.png",
"updated_at": "2019-04-22 19:22:17"
},
"total": 1,
"usage_limits": {
"monthly": {
"limit": 5000,
"usage": 32
}
}
}
.. raw:: html
|
Search icons
############
:code:`/icons/{ search_term }` → :code:`/v2/icon?query={ search_term }`
- Requesting the SVG url in the response is optional, must be specified by query parameter :code:`include_svg=1`, and is not included by default in the response
- Renamed PNG thumbnail key from :code:`preview_url` to :code:`thumbnail_url`
- Removed :code:`preview_url_42` and :code:`preview_url_84` - both can now be retrieved by specifying :code:`thumbnail_size={ size }` as a query parameter
- Renamed collections :code:`author` key to :code:`creator`
- Renamed icon :code:`author` key to :code:`creator`
- Simplified icon response
- Simplified icon creator response
- Simplified tags response
- Simplified collections response
- Added monthly API usage data in response
.. raw:: html
v1 Response
.. code-block:: json
{
"generated_at": "Wed, 22 Mar 2023 22:56:06 GMT",
"icons": [
{
"attribution": "test by ChangHoon Baek from Noun Project",
"attribution_preview_url": "https://static.thenounproject.com/attribution/84093-600.png",
"collections": [],
"date_uploaded": "2014-11-19",
"icon_url": "https://static.thenounproject.com/noun-svg/84093.svg",
"id": "84093",
"is_active": "1",
"is_explicit": "0",
"license_description": "creative-commons-attribution",
"nounji_free": "0",
"permalink": "/term/test/84093",
"preview_url": "https://static.thenounproject.com/png/84093-200.png",
"preview_url_42": "https://static.thenounproject.com/png/84093-42.png",
"preview_url_84": "https://static.thenounproject.com/png/84093-84.png",
"sponsor": {},
"sponsor_campaign_link": null,
"sponsor_id": "",
"tags": [
{
"id": 3430,
"slug": "test"
},
{
"id": 7517,
"slug": "user-interface"
},
{
"id": 11284,
"slug": "user-experience"
},
{
"id": 19319,
"slug": "ui"
},
{
"id": 6147,
"slug": "register"
},
{
"id": 469,
"slug": "paper"
},
{
"id": 4065,
"slug": "list"
},
{
"id": 6032,
"slug": "form"
},
{
"id": 2286,
"slug": "design"
},
{
"id": 4903,
"slug": "checklist"
},
{
"id": 1149,
"slug": "check"
},
{
"id": 1290,
"slug": ""
},
{
"id": 6757,
"slug": "ux"
}
],
"term": "test",
"term_id": 3430,
"term_slug": "test",
"updated_at": "2019-04-22 19:22:17",
"uploader": {
"location": "Toronto, ON, CA",
"name": "ChangHoon Baek",
"permalink": "/changhoon.baek.50",
"username": "changhoon.baek.50"
},
"uploader_id": "37574",
"year": 2014
},
{
"attribution": "test by Arthur Shlain from Noun Project",
"attribution_preview_url": "https://static.thenounproject.com/attribution/247442-600.png",
"collections": [
{
"author": {
"location": "",
"name": "Arthur Shlain",
"permalink": "/ArtZ91",
"username": "ArtZ91"
},
"author_id": "15311",
"date_created": "2014-08-20 19:59:47",
"date_updated": "2015-08-25 19:15:04",
"description": "",
"id": "866",
"is_collaborative": "",
"is_featured": "0",
"is_published": "1",
"is_store_item": "0",
"name": "Assemblage",
"permalink": "/ArtZ91/collection/assemblage",
"slug": "assemblage",
"sponsor": {},
"sponsor_campaign_link": "",
"sponsor_id": "",
"tags": [],
"template": "24"
}
],
"date_uploaded": "2015-11-13",
"icon_url": "https://static.thenounproject.com/noun-svg/247442.svg",
"id": "247442",
"is_active": "1",
"is_explicit": "0",
"license_description": "creative-commons-attribution",
"nounji_free": "0",
"permalink": "/term/test/247442",
"preview_url": "https://static.thenounproject.com/png/247442-200.png",
"preview_url_42": "https://static.thenounproject.com/png/247442-42.png",
"preview_url_84": "https://static.thenounproject.com/png/247442-84.png",
"sponsor": {},
"sponsor_campaign_link": null,
"sponsor_id": "",
"tags": [
{
"id": 3430,
"slug": "test"
},
{
"id": 5282,
"slug": "tasks"
},
{
"id": 8435,
"slug": "result"
},
{
"id": 4875,
"slug": "plan"
},
{
"id": 11469,
"slug": "grade"
},
{
"id": 3149,
"slug": "goal"
},
{
"id": 8540,
"slug": "exam"
},
{
"id": 58355,
"slug": "check-list"
},
{
"id": 16012,
"slug": "challenge"
},
{
"id": 10926,
"slug": "validation"
}
],
"term": "test",
"term_id": 3430,
"term_slug": "test",
"updated_at": "2019-04-22 19:22:17",
"uploader": {
"location": "",
"name": "Arthur Shlain",
"permalink": "/ArtZ91",
"username": "ArtZ91"
},
"uploader_id": "15311",
"year": 2015
}
]
}
.. raw:: html
v2 Response
.. code-block:: json
{
"generated_at": "2023-03-22 22:58:39.517834",
"icons": [
{
"attribution": "test by ChangHoon Baek from Noun Project",
"collections": [],
"creator": {
"name": "ChangHoon Baek",
"permalink": "/changhoon.baek.50",
"username": "changhoon.baek.50"
},
"icon_url": "https://static.thenounproject.com/svg_clean/84093.svg",
"id": "84093",
"license_description": "creative-commons-attribution",
"permalink": "/term/test/84093",
"tags": [
"test",
"user-interface",
"user-experience",
"ui",
"register",
"paper",
"list",
"form",
"design",
"checklist",
"check",
"ux"
],
"term": "test",
"thumbnail_url": "https://static.thenounproject.com/png/84093-200.png",
"updated_at": "2019-04-22 19:22:17"
},
{
"attribution": "test by Nur Achmadi Yusuf from Noun Project",
"collections": [
{
"creator": {
"name": "Nur Achmadi Yusuf",
"permalink": "/achmadi9",
"username": "achmadi9"
},
"id": "179852",
"name": "Corporate Line",
"permalink": "/achmadi9/collection/corporate-line"
}
],
"creator": {
"name": "Nur Achmadi Yusuf",
"permalink": "/achmadi9",
"username": "achmadi9"
},
"icon_url": "https://static.thenounproject.com/svg_clean/5455842.svg",
"id": "5455842",
"license_description": "creative-commons-attribution",
"permalink": "/term/test/5455842",
"tags": [
"test",
"clipboard",
"document",
"education",
"exam",
"list"
],
"term": "test",
"thumbnail_url": "https://static.thenounproject.com/png/5455842-200.png",
"updated_at": "2023-01-24 22:43:51"
}
],
"next_page": "31352E302C35343535383432",
"total": 12791,
"usage_limits": {
"monthly": {
"limit": 5000,
"usage": 31
}
}
}
.. raw:: html
|
Check API usage
###############
:code:`/oauth/usage` → :code:`/v2/oauth/usage`
- Restructured from top level keys of :code:`limit` and :code:`usage` that were then referencing 3 additional keys for :code:`hourly`, :code:`daily`, and :code:`monthly` to simply a top level key of :code:`monthly` that provides :code:`limit` and :code:`usage`
.. list-table::
:width: 100%
:class: full-width-table
* - **v1 Response**
- **v2 Response**
* - .. code-block:: json
{
"limits": {
"daily": null,
"hourly": null,
"monthly": 5000
},
"usage": {
"daily": 30,
"hourly": 16,
"monthly": 32
}
}
- .. code-block:: json
{
"monthly": {
"limit": 5000,
"usage": 440
}
}
|
Report icon usage
#################
:code:`/notify/publish` → :code:`/v2/client/report`
- Removed :code:`result` key
- Renamed :code:`licenses_consumed` to :code:`total_icons_reported`
- Added monthly API usage data in response
.. list-table::
:width: 100%
:class: full-width-table
* - **v1 Response**
- **v2 Response**
* - .. code-block:: json
{
"licenses_consumed": 3,
"result": "success"
}
- .. code-block:: json
{
"total_icons_reported": 3,
"usage_limits": {
"monthly": {
"limit": 5000,
"usage": 440
}
}
}
Examples
--------
Requesting an icon by id
########################
*v1 Example*
.. code-block:: python
import requests
from requests_oauthlib import OAuth1
auth = OAuth1("your-api-key", "your-api-secret")
endpoint = "https://api.thenounproject.com/icon/1"
response = requests.get(endpoint, auth=auth)
response_json = response.json()
icon_url = response_json["icon"]["icon_url"]
thumbnail_url = response_json["icon"]["preview_url"]
title = response_json["icon"]["term"]
tags = response_json["icon"]["tags"]
license = response_json["icon"]["license_description"]
*v2 Example*
.. code-block:: python
import requests
from requests_oauthlib import OAuth1
auth = OAuth1("your-api-key", "your-api-secret")
endpoint = "https://api.thenounproject.com/v2/icon/1"
response = requests.get(endpoint, auth=auth)
response_json = response.json()
icon_url = response_json["icon"]["icon_url"]
thumbnail_url = response_json["icon"]["thumbnail_url"]
title = response_json["icon"]["term"]
tags = response_json["icon"]["tags"]
license = response_json["icon"]["license_description"]
|
Searching icons
###############
*v1 Example*
.. code-block:: python
import requests
from requests_oauthlib import OAuth1
auth = OAuth1("your-api-key", "your-api-secret")
endpoint = "https://api.thenounproject.com/icons/test"
response = requests.get(endpoint, auth=auth)
response_json = response.json()
for icon in response_json["icons"]:
icon_url = icon["icon_url"]
thumbnail_url = icon["preview_url"]
title = icon["term"]
tags = icon["tags"]
license = icon["license_description"]
*v2 Example*
.. code-block:: python
import requests
from requests_oauthlib import OAuth1
auth = OAuth1("your-api-key", "your-api-secret")
endpoint = "https://api.thenounproject.com/v2/icon?query=test&include_svg=1"
response = requests.get(endpoint, auth=auth)
response_json = response.json()
for icon in response_json["icons"]:
icon_url = icon["icon_url"]
thumbnail_url = icon["thumbnail_url"]
title = icon["term"]
tags = icon["tags"]
license = icon["license_description"]