Overview

This document outlines the AnalogDB API. This API provides film photographs and metadata in JSON form as a REST-style service. The API is open-source and available on github. The swagger docs are available here.

The AnalogDB project is currently under development and subject to change. All film pictures are scrapped from reddit. All credit goes to the original photographers.

Use the following URI to access the endpoints: https://api.analogdb.com/v1

Rate Limiting

The Analogdb API currently places a limit of 60 requests/min. Current rate limit status is returned in response headers after each request including remaining requests and reset time in unix epoch seconds.

x-ratelimit-limit: 60
x-ratelimit-remaining: 59
x-ratelimit-reset: 1691712960

Pagination

All collection endpoints are paginated with keyset pagination. By default, 20 records are returned per page. Pagination can be controlled with the following parameters:

param	description
`page_size`	set the number of records to return on each page (default 20, maximum 200)
`cursor`	request the next page of results. Each request returns a next_cursor that can be passed back to access the next page of results
`page_id`	deprecated, use cursor

curl https://api.analogdb.com/v1/posts?page_size=10&cursor=eyJzIjoidGltZSIsInYiOjE3OTA1Mzk5MjIsImlkIjo0MDA1Mn0

Resources

Image

The image resource contains the image URL as well as resolution and dimensions.

field name	type	description
`url`	string	link to image
`resolution`	string	low, medium, high, raw
`width`	integer	width of image in pixels
`height`	integer	height of image in pixels

Color

The color resource represents primary colors extracted from images and corresponding percentages.

field name	type	description
`css`	string	CSS color name (e.g., dimgray)
`hex`	string	hex color code (e.g., #837d5c)
`html`	string	HTML color name (e.g., gray)
`percent`	number	percent of image this color represents

Keyword

The keyword resource contains keywords scraped from post along with relevance score.

field name	type	description
`word`	string	detected keyword in image
`weight`	number	relevance of keyword (0-1)

Post

The post resource contains a list of image(multiple resolutions) as well as metadata about the post including timestamp, score, camera, film, colors, keywords, etc.

field name	type	description
`id`	integer	unique identifier
`title`	string	title of post
`author`	string	author of post
`permalink`	string	url of post source
`score`	integer	total votes of post
`timestamp`	integer	time of post creation (unix time)
`description`	string	post description
`camera_make`	string	camera manufacturer (e.g., nikon)
`camera_model`	string	camera model (e.g., fm2)
`film_make`	string	film manufacturer (e.g., kodak)
`film_type`	string	film type (e.g., portra 400)
`film_speed`	integer	film ISO speed (e.g., 400)
`aperture`	string	aperture setting (e.g., f/2.0)
`focal_length`	integer	focal length in mm (e.g., 35)
`nsfw`	bool	image is NSFW (not safe for work, 18+)
`grayscale`	bool	image is grayscale (black & white)
`sprocket`	bool	image is a sprocket shot (exposed film sprockets)
`images`	array[image]	list of images at different resolutions
`colors`	array[color]	dominant colors extracted from image
`keywords`	array[keyword]	keywords extracted from post

Camera

The camera resource contains film cameras used in posts including manufacturer, model, and description and post count.

field name	type	description
`id`	integer	unique identifier
`make`	string	camera manufacturer (e.g., nikon)
`model`	string	camera model (e.g., fm2)
`description`	string	description of camera
`post_count`	integer	number of posts using this camera
`created`	string	timestamp when camera was added
`updated`	string	timestamp when camera was last updated

Film

The film resource contains film stocks used in posts, including manufacturer, type, speed, and post count.

field name	type	description
`id`	integer	unique identifier
`make`	string	film manufacturer (e.g., kodak)
`type`	string	film type (e.g., portra 400)
`speed`	integer	film ISO speed (e.g., 400)
`color_type`	string	color or black & white film
`description`	string	description of film
`post_count`	integer	number of posts using this film
`created`	string	timestamp when film was added
`updated`	string	timestamp when film was last updated

field name	type	description
`total_posts`	integer	total number of posts served by endpoint query
`page_size`	integer	maximum number of posts returned per page
`next_cursor`	string	cursor for the next page, empty on the last page
`next_page_id`	integer	deprecated, use next_cursor
`next_page_url`	string	url path to fetch next page
`seed`	integer	random seed used for random sorting

Endpoints

/posts

Returns a collection of post resources with accompanying meta resource. Supports extensive filtering and sorting options.

General Parameters

Posts can be sorted by time, score, or pseudo-randomly. Limits can be placed for maximum number of returned posts. If total number of posts exceeds the limit, results will be paginated.

param	description	default	options
`sort`	how to order the posts	time	time, score, random
`page_size`	maximum number of posts returned	20	1-200
`cursor`	cursor of page to retrieve, from next_cursor	null
`page_id`	deprecated, use cursor	null
`seed`	random seed for consistent random sorting	null	integer

curl https://api.analogdb.com/v1/posts?sort=score&page_size=50

Filter Parameters

Posts can be filtered by various criteria including camera, film, time, colors, keywords, and image dimensions. For boolean filters (nsfw, grayscale, sprocket) if not provided, all posts are included; if set to true, only that type is returned; if set to false, that type is excluded.

param	description
`id`	filter by post ID
`title`	filter by post title
`author`	filter by author
`time_start`	filter by start time (unix timestamp)
`time_end`	filter by end time (unix timestamp)
`camera_make`	filter by camera make
`camera_model`	filter by camera model
`film_make`	filter by film make
`film_type`	filter by film type
`film_speed`	filter by film speed
`focal_length`	filter by focal length
`aperture`	filter by aperture
`nsfw`	include nsfw (18+) images (true=only, false=exclude)
`grayscale`	include grayscale (black & white) images (true=only, false=exclude)
`sprocket`	include sprocket images (true=only, false=exclude)
`keyword`	filter by keywords (multiple allowed)
`color`	color filter (multiple allowed)
`min_color`	minimum color percentage (multiple allowed)
`width_min`	minimum picture width
`width_max`	maximum picture width
`height_min`	minimum picture height
`height_max`	maximum picture height
`ratio_min`	minimum picture aspect ratio
`ratio_max`	maximum picture aspect ratio

curl 'https://api.analogdb.com/v1/posts?camera_make=nikon&film_make=kodak&grayscale=false&keyword=portrait'

/post/:id

Returns a single specific post resource as identified by ID.

curl https://api.analogdb.com/v1/post/1924

/post/:id/similar

Returns a collection of post resources that are visually similar to the specified post based on vector similarity of image embeddings.

param	description	options
`id`	post ID to find similar posts for (required)	integer
`page_size`	maximum number of similar posts to return	1-200 (default: 12)
`nsfw`	include nsfw posts in results	boolean
`grayscale`	include grayscale posts in results	boolean
`sprocket`	include sprocket posts in results	boolean

curl https://api.analogdb.com/v1/post/1924/similar?page_size=20&nsfw=false

/cameras

Returns a collection of camera resources with optional filtering and sorting. Useful for discovering cameras (not extensive) and their post counts.

param	description	options
`sort`	sort order	alphabetical, counts
`page_size`	number of results to return	integer
`make`	filter by camera make	string
`model`	filter by camera model	string
`id`	filter by specific camera ID	integer
`include_counts`	include post counts	boolean
`exclude_zero_counts`	exclude cameras with zero post counts	boolean

curl https://api.analogdb.com/v1/cameras?sort=counts&make=nikon&include_counts=true

/films

Returns a collection of film resources with optional filtering and sorting. Useful for discovering film stocks (not extensive) and their post counts.

param	description	options
`sort`	sort order	alphabetical, counts
`page_size`	number of results to return	integer
`make`	filter by film make	string
`type`	filter by film type	string
`speed`	filter by film speed	integer
`colortype`	filter by color type	string
`id`	filter by specific film ID	integer
`include_counts`	include post counts	boolean
`exclude_zero_counts`	exclude films with zero post counts	boolean

curl https://api.analogdb.com/v1/films?sort=counts&make=kodak&speed=400&include_zero_counts=true