Yarn Colorways API
Find yarn colorways by HTML hex color code.
The Yarn Colorways API is a JSON API providing access to the yarn database from temperature-blanket.com.
Yarn details and HTML hex color codes are added by the developer of temperature-blanket.com at the request of users using this form.
HTML hex colors are approximations of fiber colors. Real yarn colors will look different than what’s on a screen. Any trademarked yarn or colorway details are owned by their respective companies.
The data is provided “as is” and without any guarantees of quality, performance, or suitability for any purpose.
Using the API
Sign Up
temperature-blanket.com uses RapidAPI for delivering the Yarn Colorways API.
Access to the API requires users to send their RapidAPI key along with every request. Create an account and subscribe to one of the plans to get a key for accessing the Yarn Colorways API. The free plan allows up to 500 calls per month.
Making a Request
This is the base URL for all endpoints:
https://yarn-colorways.p.rapidapi.com/v1
Include the following headers:
"X-RapidAPI-Key": 'your-rapidapi-key',
"X-RapidAPI-Host":
"yarn-colorways.p.rapidapi.com"
All requests should use the GET method.
Reading a Response
A successful response will return a JSON object that contains two properties: meta and data. The meta object provides general information about the data. The data property is an array that contains the actual data output.
Here's an example of a successful response from the /colorways endpoint.
{ "meta": { "limit": 50, // the maxmimum number of results "offset": 0, // the starting index of the results "total": 6743 // the total number of results }, "data": [ { "name": "Olive" "hex": "#665e3f" "brandId": "bernat" "brandName": "Bernat" "yarnId": "blanket" "yarnName": "Blanket" "yarnWeightId": 'sb' "dateAccessed": "2024-01-19" "href": "https://www.yarnspirations.com/products/bernat-blanket-yarn-300g-10-5oz-1" }, ... ] }
If you encouter an error, look at the Status Codes to find out why.
Endpoints
Find Yarn by Color
Get best-matching yarn colorways for a specified color.
Method GET
URL /match/[color]
Parameters
When calling this endpoint, refer to the following parameters.
| Parameter | Description | Type | Required | Default |
|---|---|---|---|---|
| color | An HTML hex color code, or any string that can be correctly parsed as a color by chroma.js (just make sure the string is URL encoded). | String | Yes | undefined |
| brand | A brand ID or name, or a comma-separated list of brand IDs or brand names to filter the results by. | String | No | undefined |
| yarn | A yarn ID or name, or a comma-separated list of yarn IDs or yarn names to filter the results by. | String | No | undefined |
| weight | A yarn weight ID or name. | String | No | undefined |
| limit | The maximum number of yarn colorways to include in the results. Maximum is 500. | Number | No | 50 |
| offset | The starting index of the data to return. | Number | No | 0 |
| threshold | The minimum percentage amount the yarn colorway must match the supplied color, between 0 and 100. | Number | No | 75 |
Examples
// get colorways matching an HTML hex code without the # hash GET https://yarn-colorways.p.rapidapi.com/v1/match/665e3f // get colorways matching a URL encoded HTML hex code #665e3f GET https://yarn-colorways.p.rapidapi.com/v1/match/%23665e3f // get colorways matching a standard HTML color name GET https://yarn-colorways.p.rapidapi.com/v1/match/green // get colorways matching a URL encoded RGB color code rgb(102,94,63) GET https://yarn-colorways.p.rapidapi.com/v1/match/rgb%28102%2C94%2C63%29 // get matches only from a specified brand and yarn GET https://yarn-colorways.p.rapidapi.com/v1/match/665e3f?brand=cascade&yarn=anchor_bay
Response
A successful response's data property will contain an array of colorway objects with the following properties:
| Parameter | Description | Type |
|---|---|---|
| name | The name of the colorway. | String |
| hex | The HTML hex color code of the colorway. | String |
| yarnId | The ID of the yarn. | String |
| yarnName | The name of the yarn. | String |
| yarnWeightId | The id of the yarn weight. | String |
| brandId | The ID of the brand. | String |
| brandName | The name of the brand. | String |
| dateAccessed | YYYY-MM-DD date when the colorway was added to the database. | String |
| href | The webpage where the colorway was found. | String |
| delta | The calculated difference between the specified color and the yarn colorway hex, between 0 (most similar) and 100 (most different). | Number |
| percentMatch | The percentage that the supplied color matches the colorway hex, rounded down to the nearest integer. | Number |
Colorways
Get yarn colorways.
Method GET
URL /colorways
Parameters
When calling this endpoint, refer to the following parameters.
| Parameter | Description | Type | Required | Default |
|---|---|---|---|---|
| color | An HTML hex color code, or any string that can be correctly parsed as a color by chroma.js (just make sure the string is URL encoded). | String | No | undefined |
| name | Any colorway name. Text case is ignored. | String | No | undefined |
| brand | A brand ID or name, or a comma-separated list of brand IDs or brand names to filter the results by. | String | No | undefined |
| yarn | A yarn ID or name, or a comma-separated list of yarn IDs or yarn names to filter the results by. | String | No | undefined |
| weight | A yarn weight ID or name. | String | No | undefined |
| limit | The maximum number of yarn colorways to include in the results. Maximum is 500. | Number | No | 50 |
| offset | The starting index of the data to return. | Number | No | 0 |
| sortBy | The property to sort the results by. Accepted values are default, lightness, or name. | String | No | default |
| direction | The direction to sort the results. Accepted values are ASC (ascending) or DESC (descending). | String | No | ASC |
Example
// get all colorways GET https://yarn-colorways.p.rapidapi.com/v1/colorways // get all colorways from a specified brand and yarn, sorted by lightest-to-darkest GET https://yarn-colorways.p.rapidapi.com/v1/colorways?brand=premire&yarn=afternoon_cotton&sortBy=lightness // get all colorways with a specified name GET https://yarn-colorways.p.rapidapi.com/v1/colorways?name=peach
Response
A successful response's data property will contain an array of colorway objects with the following properties:
| Parameter | Description | Type |
|---|---|---|
| name | The name of the colorway. | String |
| hex | The HTML hex color code of the colorway. | String |
| yarnId | The ID of the yarn. | String |
| yarnName | The name of the yarn. | String |
| yarnWeightId | The id of the yarn weight. | String |
| brandId | The ID of the brand. | String |
| brandName | The name of the brand. | String |
| dateAccessed | YYYY-MM-DD date when the colorway was added to the database. | String |
| href | The webpage where the colorway was found. | String |
Brands
Get all brand IDs and names, useful to filter /match or /colorways results.
Method GET
URL /brands
Parameters
There are no parameters when calling this request.
Example
// get all brands GET https://yarn-colorways.p.rapidapi.com/v1/brands
Response
A successful response's data property will contain an array of brand objects with the following properties:
| Parameter | Description | Type |
|---|---|---|
| brandName | The name of the brand. | String |
| brandId | The ID of the brand. | String |
| yarns | The number of yarns in this brand. | Number |
| colorways | The number of colorways in this brand. | Number |
Yarns
Get all yarn IDs and names, useful to filter /match or /colorways results.
Method GET
URL /yarns
Parameters
When calling this endpoint, refer to the following parameters.
| Parameter | Description | Type | Required | Default |
|---|---|---|---|---|
| brand | The brand ID or name, or a comma-separated list of brand IDs or brand names to filter the results by. | String | No | undefined |
Example
// get all yarns GET https://yarn-colorways.p.rapidapi.com/v1/yarns // filter by brand GET https://yarn-colorways.p.rapidapi.com/v1/yarns?brand=hobbii // filter by multiple brands GET https://yarn-colorways.p.rapidapi.com/v1/yarns?brand=bernat,loops_and_threads,plymouth_yarn
Response
A successful response's data property will contain an array of yarn objects with the following properties:
| Parameter | Description | Type |
|---|---|---|
| brandName | The name of the brand. | String |
| brandId | The ID of the brand. | String |
| yarnId | The ID of the yarn. | String |
| yarnName | The name of the yarn. | String |
| yarnWeightId | The id of the yarn weight. | String |
| colorways | The number of colorways in this yarn. | Number |
Yarn Weights
Get all yarn weight IDs and names, useful to filter /match or /colorways results.
Method GET
URL /weights
Parameters
There are no parameters when calling this request.
Example
// get all yarn weights GET https://yarn-colorways.p.rapidapi.com/v1/weights
Response
A successful response's data property will contain an array of yarn weight objects with the following properties:
| Parameter | Description | Type |
|---|---|---|
| id | The id of the yarn weight. | String |
| name | The name of the yarn weight. | String |
| yarns | The number of yarns in this weight | String |
Status Codes
Responses will have one of the following status codes:
| Code | Description |
|---|---|
| 200 | Success: All is fine |
| 400 | Bad Request: Please check the query parameters |
| 401 | Unauthorized: Make sure to send a valid RapidAPI key |
| 403 | Forbidden: You're not allowed to access this endpoint |
| 404 | Not Found: This endpoint doesn't exist |
| 429 | Too Many Requests: You've exceeded the quota |
| 503 | Service Temporarily Unavailable: The API is currently down |
Terms & License
Data is provided under the terms of the CC BY 4.0 DEED Attribution 4.0 International license.
You are free to:
Share — copy and redistribute the material in any medium or format for any purpose, even commercially.
Adapt — remix, transform, and build upon the material for any purpose, even commercially.
Under the following terms:
Attribution — You must give appropriate credit, provide a link to this license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
Example Attribution:
Yarn colorways from temperature-blanket.com licensed under CC BY 4.0 DEED.
HTML hex colors are approximations of fiber colors. Real yarn colors will look different than what’s on a screen. Any trademarked yarn or colorway details are owned by their respective companies.
The data is provided “as is” and without any guarantees of quality, performance, or suitability for any purpose.