Version 5 | See what's new
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.

ParameterDescriptionTypeRequiredDefault
colorAn 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).StringYesundefined
brandA brand ID or name, or a comma-separated list of brand IDs or brand names to filter the results by.StringNoundefined
yarnA yarn ID or name, or a comma-separated list of yarn IDs or yarn names to filter the results by.StringNoundefined
weightA yarn weight ID or name.StringNoundefined
limitThe maximum number of yarn colorways to include in the results. Maximum is 500.NumberNo50
offsetThe starting index of the data to return.NumberNo0
thresholdThe minimum percentage amount the yarn colorway must match the supplied color, between 0 and 100.NumberNo75

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:

ParameterDescriptionType
nameThe name of the colorway.String
hexThe HTML hex color code of the colorway.String
yarnIdThe ID of the yarn.String
yarnNameThe name of the yarn.String
yarnWeightIdThe id of the yarn weight.String
brandIdThe ID of the brand.String
brandNameThe name of the brand.String
dateAccessedYYYY-MM-DD date when the colorway was added to the database.String
hrefThe webpage where the colorway was found.String
deltaThe calculated difference between the specified color and the yarn colorway hex, between 0 (most similar) and 100 (most different).Number
percentMatchThe 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.

ParameterDescriptionTypeRequiredDefault
colorAn 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).StringNoundefined
nameAny colorway name. Text case is ignored.StringNoundefined
brandA brand ID or name, or a comma-separated list of brand IDs or brand names to filter the results by.StringNoundefined
yarnA yarn ID or name, or a comma-separated list of yarn IDs or yarn names to filter the results by.StringNoundefined
weightA yarn weight ID or name.StringNoundefined
limitThe maximum number of yarn colorways to include in the results. Maximum is 500.NumberNo50
offsetThe starting index of the data to return.NumberNo0
sortByThe property to sort the results by. Accepted values are default, lightness, or name.StringNodefault
directionThe direction to sort the results. Accepted values are ASC (ascending) or DESC (descending).StringNoASC

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:

ParameterDescriptionType
nameThe name of the colorway.String
hexThe HTML hex color code of the colorway.String
yarnIdThe ID of the yarn.String
yarnNameThe name of the yarn.String
yarnWeightIdThe id of the yarn weight.String
brandIdThe ID of the brand.String
brandNameThe name of the brand.String
dateAccessedYYYY-MM-DD date when the colorway was added to the database.String
hrefThe 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:

ParameterDescriptionType
brandNameThe name of the brand.String
brandIdThe ID of the brand.String
yarnsThe number of yarns in this brand.Number
colorwaysThe 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.

ParameterDescriptionTypeRequiredDefault
brandThe brand ID or name, or a comma-separated list of brand IDs or brand names to filter the results by.StringNoundefined

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:

ParameterDescriptionType
brandNameThe name of the brand.String
brandIdThe ID of the brand.String
yarnIdThe ID of the yarn.String
yarnNameThe name of the yarn.String
yarnWeightIdThe id of the yarn weight.String
colorwaysThe 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:

ParameterDescriptionType
idThe id of the yarn weight.String
nameThe name of the yarn weight.String
yarnsThe number of yarns in this weightString

Status Codes

Responses will have one of the following status codes:

CodeDescription
200Success: All is fine
400Bad Request: Please check the query parameters
401Unauthorized: Make sure to send a valid RapidAPI key
403Forbidden: You're not allowed to access this endpoint
404Not Found: This endpoint doesn't exist
429Too Many Requests: You've exceeded the quota
503Service 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.