Free Photos API

This guide will help you understand how to interact with the Photos API, which allows you to search, retrieve, and manage photo data. The API supports operations like fetching a list of photos, getting random photos, and retrieving a specific photo by its ID. Below, you'll find detailed information on each endpoint, including examples of how to use them.

Notes:

The API returns data in JSON format, making it easy to integrate with your frontend applications.
No API key is required. No rate limit.
The title and description of each photo is just dummy text (the purpose of this API is only for learning, testing, and prototyping new ideas).

You can try the photos API online here.

Base URL

The base URL for accessing the Photos API is:

https://boringapi.com/api/v1/photos

There are 3 endpoints. The first one gives you a list of photos . The second one provides one or multiple random photos. The last one allows you to get a single photo by its ID.

Get Photos

Endpoint:

GET https://boringapi.com/api/v1/photos

Fetch a list of photos with optional search, pagination, and sorting.

Query Parameters:

search (string, optional): Search for photos by title or description.
page (integer, optional): The page number of photos to return (default: 1).
limit (integer, optional): The number of photos to return per page (default: 10, min: 1, max: 100).
sort_by (string, optional): The field to sort photos by (default: 'id'). Possible values: 'id', 'title', 'file_size', 'width', 'height', 'created_at', 'updated_at'.
sort_order (string, optional): The order to sort photos by (default: 'desc'). Possible values: 'asc', 'desc'.

Response:

{
    "success": true,
    "message": "Page 1 of photos, sorted by 'id' in 'desc' order.",
    "count": 10,
    "total_pages": 30,
    "photos": [
        {
            "id": 300,
            "width": 1280,
            "created_at": "2024-06-17T09:42:10.736482",
            "title": "Plan pattern late somebody",
            "description": "Occur sure left wind statement painting. List several system support notice wish traditional.",
            "file_size": 192,
            "height": 853,
            "updated_at": "2024-06-17T09:42:10.736482",
            "url": "https://boringapi.com/api/v1/static/photos/300.jpeg"
        },
        ...
    ]
}

Example:

curl -X GET "https://boringapi.com/api/v1/photos/?search=landscape&page=1&limit=10&sort_by=title&sort_order=asc"

Get Random Photos

Endpoint:

GET https://boringapi.com/api/v1/photos

Fetch a specified number of random photos.

Query Parameters:

num (integer, optional): The number of random photos to return (default: 1, min: 1, max: 10).

Response:

{
  "success": true,
  "message": "Here are 2 random photos!",
  "photos": [
    {
      "id": 3,
      "title": "Random Photo Title 1",
      "description": "Random Photo Description 1",
      "url": "full photo URL 1",
      "file_size": 130.2,
      "width": 1024,
      "height": 768,
      "created_at": "2023-01-01T00:00:00",
      "updated_at": "2023-01-01T00:00:00"
    },
    {
      "id": 7,
      "title": "Random Photo Title 2",
      "description": "Random Photo Description 2",
      "url": "full photo URL 2",
      "file_size": 150.3,
      "width": 800,
      "height": 600,
      "created_at": "2023-01-01T00:00:00",
      "updated_at": "2023-01-01T00:00:00"
    }
  ]
}

Example:

curl -X GET "https://boringapi.com/api/v1/photos/random?num=2"

Get a Single Photo

Endpoint:

GET https://boringapi.com/api/v1/photos/{photo_id}

Fetch a single photo by its ID.

Path Parameters:

photo_id (integer, required): The ID of the photo.

Response:

{
  "success": true,
  "message": "Photo with ID 1 found!",
  "photo": {
    "id": 1,
    "title": "Photo Title",
    "description": "Photo Description",
    "url": "full photo URL",
    "file_size": 120.5,
    "width": 800,
    "height": 600,
    "created_at": "2023-01-01T00:00:00",
    "updated_at": "2023-01-01T00:00:00"
  }
}

Example request:

curl -X GET "https://boringapi.com/api/v1/photos/1"\

Code Examples

Here are four code examples showing how to make API calls to the Photos API using JavaScript (fetch API), Python (aiohttp), Java, and Swift.

JavaScript (Fetch API)

// Example: Get a list of photos
fetch('https://boringapi.com/api/v1/photos/?page=1&limit=10')
    .then(response => response.json())
    .then(data => {
        console.log('Success:', data);
    })
    .catch((error) => {
        console.error('Error:', error);
    });
// Example: Get a single photo by ID
fetch('https://boringapi.com/api/v1/photos/1')
    .then(response => response.json())
    .then(data => {
        console.log('Success:', data);
    })
    .catch((error) => {
        console.error('Error:', error);
    });

Python (aiohttp)

import aiohttp
import asyncio
async def fetch_photos():
    async with aiohttp.ClientSession() as session:
        async with session.get('https://boringapi.com/api/v1/photos/?page=1&limit=10') as response:
            data = await response.json()
            print('Success:', data)
async def fetch_single_photo(photo_id):
    async with aiohttp.ClientSession() as session:
        async with session.get(f'https://boringapi.com/api/v1/photos/{photo_id}') as response:
            data = await response.json()
            print('Success:', data)
# Example usage
async def main():
    await fetch_photos()
    await fetch_single_photo(1)
if __name__ == "__main__":
    asyncio.run(main())

Java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class Main {
    public static void main(String[] args) {
        try {
            fetchPhotos();
            fetchSinglePhoto(1);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    public static void fetchPhotos() throws Exception {
        String url = "https://boringapi.com/api/v1/photos/?page=1&limit=10";
        HttpURLConnection httpClient = (HttpURLConnection) new URL(url).openConnection();
        // optional default is GET
        httpClient.setRequestMethod("GET");
        int responseCode = httpClient.getResponseCode();
        System.out.println("GET Response Code :: " + responseCode);
        if (responseCode == HttpURLConnection.HTTP_OK) { // success
            BufferedReader in = new BufferedReader(new InputStreamReader(httpClient.getInputStream()));
            String inputLine;
            StringBuilder response = new StringBuilder();
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();
            // print result
            System.out.println(response.toString());
        } else {
            System.out.println("GET request not worked");
        }
    }
    public static void fetchSinglePhoto(int photoId) throws Exception {
        String url = "https://boringapi.com/api/v1/photos/" + photoId;
        HttpURLConnection httpClient = (HttpURLConnection) new URL(url).openConnection();
        // optional default is GET
        httpClient.setRequestMethod("GET");
        int responseCode = httpClient.getResponseCode();
        System.out.println("GET Response Code :: " + responseCode);
        if (responseCode == HttpURLConnection.HTTP_OK) { // success
            BufferedReader in = new BufferedReader(new InputStreamReader(httpClient.getInputStream()));
            String inputLine;
            StringBuilder response = new StringBuilder();
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();
            // print result
            System.out.println(response.toString());
        } else {
            System.out.println("GET request not worked");
        }
    }
}

Swift

import Foundation
func fetchPhotos() {
    let url = URL(string: "https://boringapi.com/api/v1/photos/?page=1&limit=10")!
    
    let task = URLSession.shared.dataTask(with: url) { data, response, error in
        guard let data = data, error == nil else {
            print("Error:", error ?? "Unknown error")
            return
        }
        
        if let httpResponse = response as? HTTPURLResponse, httpResponse.statusCode == 200 {
            do {
                let jsonResponse = try JSONSerialization.jsonObject(with: data, options: [])
                print("Success:", jsonResponse)
            } catch let parsingError {
                print("Error:", parsingError)
            }
        } else {
            print("Failed to fetch photos")
        }
    }
    
    task.resume()
}
func fetchSinglePhoto(photoId: Int) {
    let url = URL(string: "https://boringapi.com/api/v1/photos/\(photoId)")!
    
    let task = URLSession.shared.dataTask(with: url) { data, response, error in
        guard let data = data, error == nil else {
            print("Error:", error ?? "Unknown error")
            return
        }
        
        if let httpResponse = response as? HTTPURLResponse, httpResponse.statusCode == 200 {
            do {
                let jsonResponse = try JSONSerialization.jsonObject(with: data, options: [])
                print("Success:", jsonResponse)
            } catch let parsingError {
                print("Error:", parsingError)
            }
        } else {
            print("Failed to fetch photo")
        }
    }
    
    task.resume()
}
// Example usage
fetchPhotos()
fetchSinglePhoto(photoId: 1)

Back to Home