cheatsnake / xcolors-api

🌈 HTTP API for generating & converting colors.

🌈 xColors API

A free API for generate & convert colors.

👓 Overview

xColors is a completely free service that provides the ability to get random colors and convert them into various color models (HEX, RGB and HSL are supported). All data comes in a convenient JSON format, so you can immediately use them for styling in CSS without additional validation.

📄 API Documentation

🎲 Get random color

Get a JSON object that contains a random color in three HEX, RGB and HSL color models at once.

https://x-colors.yurace.pro/api/random

{
    hex: "#CCFB7B",
    rgb: "rgb(204, 251, 123)",
    hsl: "hsl(82, 51%, 98%)"
}

🎨 Get random color with a given hue

You can get random shades of the color you need. For example, using reserved names such as:
[ red, pink, puprle, navy, blue, aqua, green, lime, yellow, orange ]

https://x-colors.yurace.pro/api/random/blue

Instead of reserved words, you can use any number from the range [0, 359] - which corresponds to the HUE scale.

https://x-colors.yurace.pro/api/random/228

🔧 Parameters

The number parameter allows you to get an array containing the desired number of random colors.

?number=3

The type parameter allows you to get either only a dark or light shade of color. This allows you to know in advance what font color to use against the background of the resulting color. Usually, the font color is white on dark colors, and black on light colors.

It works if you have specified the {hue}/{color} you need or use all - for an any color.

/random/{hue/color/all}?type=dark

/random/{hue/color/all}?type=light

🔄 Converting сolors

You can freely convert colors between three color models. To do this, use the desired endpoint and use the value parameter to specify the color value of the color model, depending on the selected endpoint.

Convert HEX to RGB

https://x-colors.yurace.pro/api/hex2rgb?value=FFFFFF

Convert HEX to HSL

https://x-colors.yurace.pro/api/hex2hsl?value=FFFFFF

Convert RGB to HEX

https://x-colors.yurace.pro/api/rgb2hex?value=120-200-30

Convert RGB to HSL

https://x-colors.yurace.pro/api/rgb2hsl?value=120-200-30

Convert HSL to HEX

https://x-colors.yurace.pro/api/hsl2hex?value=300-90-50

Convert HSL to RGB

https://x-colors.yurace.pro/api/hsl2rgb?value=300-90-50

🎯 Examples

https://x-colors.yurace.pro/api/random?number=10

https://x-colors.yurace.pro/api/random/green?number=10&type=light

https://x-colors.yurace.pro/api/random/123?type=dark&number=2

https://x-colors.yurace.pro/api/hsl2hex/?value=hsl(200,20,10)

https://x-colors.yurace.pro/api/hex2rgb/?value=e2A4bF

⚡ Available Scripts

In the project directory, you can:

• Run the server with Nodemon for development

npm run dev

The page will reload if you make edits.
You will also see any lint errors in the console.
Open http://localhost:5000 to view it in the browser.

• Launch tests

npm run test

• Create a production build

npm run build

• Runs the server of production build

npm start

Open http://localhost:5000 to view it in the browser.

🐳 Docker startup

1. Build docker image from Dockerfile:

docker build . -t xcolors

2. Create docker container from new image:

docker run -p 5000:5000 -d --name xcolors-server xcolors

xcolors-api's Issues

Migrated from Heroku

Migrated from Heroku

Hello, Developers! Due to the closure of free hosting service Heroku, I decided to move all my public APIs projects on my own server. The app continues to work as usual, you just need to replace the old address x-colors.herrokuapp.com with the new permanent domain name x-colors.yurace.pro.

Thank you for continuing to use the xColors API!

API data issue.

Hi, I am using your color api on one of my project but there is an issue in the API. For example if I search with some specific colors like black, white, maroon, teal etc then the api is not returning the appropriate colors. Please look into this on priority. Anticipating a response.

Requesting random colors of a specified shade returns invalid HSL color codes

When making a request such as https://x-colors.herokuapp.com/api/random/blue?number=8&type=light wherein a shade is specified, the response will contain invalid HSL color codes, missing the % sign in the lightness component, as follows:

"hsl" : "hsl(100, 98%, 66)"

This also happens if the specified shade is all, but not if nothing is specified

[kett] ~ curl "https://x-colors.herokuapp.com/api/random/all?number=1" 2>/dev/null | json_pp
{
   "hex" : "#03871D",
   "hsl" : "hsl(132, 98%, 53)",
   "rgb" : "rgb(3, 135, 29)"
}

[kett] ~ curl "https://x-colors.herokuapp.com/api/random?number=1" 2>/dev/null | json_pp    
{
   "hex" : "#661E06",
   "hsl" : "hsl(15, 94%, 40%)",
   "rgb" : "rgb(102, 30, 6)"
}

I didn't dig deep in the code, but I'm pretty sure this is all due to the missing percentage sign in the following line:

xColors-api/src/services/color.service.ts

Line 21 in 69227f7

const hsl = `hsl(${hueData(hue)}, ${saturation}%, ${randomLightness(type)})`;

Application Error?

API/site was working on Friday but now getting this error?

API not working

Hello , I´m currently using your color API for a project but it has stopped working.

The website takes a lot of time to load and then fails.

Conversion to HSL is incorrect

convertRgbToHsl seems to output the same values a conversion to HSV/HSB would, rather than to HSL.