🎉 This web app is now open source!

Yarn Colorways API

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.

See the terms of use and license.

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.