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¶

v1 Endpoint	v2 Endpoint
`/icon/{ icon_id }`	`/v2/icon/{ icon_id }`
`/icons/{ search_term }`	`/v2/icon?query={ search_term }`
`/oauth/usage`	`/v2/oauth/usage`
`/notify/publish`	`/v2/client/report`

Responses: v1 → v2 changes¶

Request a single icon by id¶

/icon/{ icon_id } → /v2/icon/{ icon_id }

Renamed PNG thumbnail key from preview_url to thumbnail_url
Removed preview_url_42 and preview_url_84 - both can now be retrieved by specifying thumbnail_size={ size } as a query parameter
Renamed collections author key to creator
Renamed icon author key to creator
Simplified icon response
Simplified icon creator response
Simplified tags response
Simplified collections response
Added monthly API usage data in response

v1 Response

{
  "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
  }
}

v2 Response

{
  "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
    }
  }
}

Search icons¶

/icons/{ search_term } → /v2/icon?query={ search_term }

Requesting the SVG url in the response is optional, must be specified by query parameter include_svg=1, and is not included by default in the response
Renamed PNG thumbnail key from preview_url to thumbnail_url
Removed preview_url_42 and preview_url_84 - both can now be retrieved by specifying thumbnail_size={ size } as a query parameter
Renamed collections author key to creator
Renamed icon author key to creator
Simplified icon response
Simplified icon creator response
Simplified tags response
Simplified collections response
Added monthly API usage data in response

v1 Response

{
  "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
    }
  ]
}

v2 Response

{
  "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
    }
  }
}

Check API usage¶

/oauth/usage → /v2/oauth/usage

Restructured from top level keys of limit and usage that were then referencing 3 additional keys for hourly, daily, and monthly to simply a top level key of monthly that provides limit and usage

v1 Response	v2 Response
{ "limits": { "daily": null, "hourly": null, "monthly": 5000 }, "usage": { "daily": 30, "hourly": 16, "monthly": 32 } }	{ "monthly": { "limit": 5000, "usage": 440 } }

Report icon usage¶

/notify/publish → /v2/client/report

Removed result key
Renamed licenses_consumed to total_icons_reported
Added monthly API usage data in response

v1 Response	v2 Response
{ "licenses_consumed": 3, "result": "success" }	{ "total_icons_reported": 3, "usage_limits": { "monthly": { "limit": 5000, "usage": 440 } } }

Examples¶

Requesting an icon by id¶

v1 Example

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

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

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

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"]