API Documentation
Introduction
Welcome to the placehold.cloud API documentation. Our API allows you to generate custom placeholder images, lorem ipsum text, quotes, jokes, weather information, recipes, and holdicons programmatically. This comprehensive guide will help you integrate our services into your applications with ease.
Authentication
No authentication is required to use our API. However, please be mindful of our rate limits and fair usage policy. We recommend including your application name in the User-Agent header for better request tracking and support.
Base URL
All API requests should be made to:
https://api.placehold.cloud/v1
Endpoints
1. Placeholder Images
Endpoint: /image/{width}/{height}
Method: GET
Parameters:
- width (required): Width of the image in pixels
- height (required): Height of the image in pixels
- background (optional): Background color (hex code without #)
- text (optional): Custom text to display on the image
- font (optional): Font family for the text (default: Arial)
- format (optional): Image format (jpg, png, webp; default: png)
Example: /image/300/200?background=ff0000&text=Hello%20World&font=Roboto&format=webp
2. Lorem Ipsum
Endpoint: /lorem-ipsum
Method: GET
Parameters:
- paragraphs (optional): Number of paragraphs to generate (default: 1)
- words (optional): Number of words per paragraph (default: 100)
- format (optional): Output format (html, text; default: text)
Example: /lorem-ipsum?paragraphs=3&words=50&format=html
3. Quotes
Endpoint: /quotes
Method: GET
Parameters:
- category (optional): Specific category of quotes (e.g., inspirational, funny, love)
- author (optional): Filter quotes by author name
Returns a random quote or a quote matching the specified criteria.
Example: /quotes?category=inspirational&author=Einstein
4. Jokes
Endpoint: /jokes
Method: GET
Parameters:
- category (optional): Joke category (e.g., programming, general, knock-knock)
- lang (optional): Language of the joke (default: en)
Returns a random joke or a joke from the specified category.
Example: /jokes?category=programming&lang=en
5. Weather
Endpoint: /weather
Method: GET
Parameters:
- city (required): Name of the city
- country (optional): Country code (e.g., US, GB, FR)
- units (optional): Units of measurement (metric, imperial; default: metric)
Example: /weather?city=London&country=GB&units=metric
6. Recipes
Endpoint: /recipes
Method: GET
Parameters:
- category (optional): Category of recipes (e.g., breakfast, lunch, dinner)
- cuisine (optional): Cuisine type (e.g., Italian, Mexican, Chinese)
- diet (optional): Dietary restrictions (e.g., vegetarian, vegan, gluten-free)
- limit (optional): Number of recipes to return (default: 1, max: 10)
Example: /recipes?category=dinner&cuisine=Italian&diet=vegetarian&limit=5
7. Holdicons
Endpoint: /holdicons/{size}
Method: GET
Parameters:
- size (required): Size of the icon in pixels (e.g., 32, 64, 128)
- text (optional): Text to generate an icon from (if not provided, a random icon will be generated)
- color (optional): Color of the icon (hex code without #)
- background (optional): Background color (hex code without #)
Returns a random icon or an icon generated based on the provided text.
Example: /holdicons/64?text=ABC&color=ffffff&background=000000
Rate Limits
To ensure fair usage, we limit requests to 100 per hour per IP address. If you exceed this limit, you'll receive a 429 Too Many Requests response. The response will include a Retry-After header indicating how long to wait before making another request.
Error Handling
Our API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
- 2xx range indicate success
- 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted)
- 5xx range indicate an error with our servers
Support
If you have any questions or need assistance with our API, please don't hesitate to contact our support team at api-support@placehold.cloud. We're here to help you integrate our services seamlessly into your applications.