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 scraped from reddit. All credit goes to the original photographers.

Use the following URI to access the endpoints: https://api.analogdb.com/v1. Paths without /v1 have been removed.

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. Requests over the limit return status 429.

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

Errors

Errors return a non 2xx status with a JSON body holding a message.

{"error": "post not found"}

param	description
`400`	invalid parameter or request
`404`	post or keyword not found
`413`	uploaded image is larger than 5 MB
`415`	uploaded image is not JPEG, PNG or WebP
`429`	rate limit exceeded
`500`	internal server error
`503`	search is busy, try again shortly

Pagination

/posts and /search are paginated with cursors. By default, 20 posts are returned per page. Pass the next_cursor from one response to get the next page, or follow next_page_url, a path relative to /v1. Other endpoints return a single page sized by page_size.

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

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. Fields that are unknown, such as camera or film, are left out.

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)
`created`	string	time the post was added to AnalogDB (RFC 3339)
`updated`	string	time the post was last changed in AnalogDB (RFC 3339)
`description`	string	post description
`caption`	string	generated description of the image
`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

Catalog Post

The catalog post resource is a short form of a post, attached to cameras, films and keywords.

field name	type	description
`id`	integer	unique identifier
`title`	string	title of post
`score`	integer	total votes of post
`images`	array[image]	list of images at different resolutions

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)
`slug`	string	url name (e.g., nikon-fm2)
`description`	string	description of camera
`post_count`	integer	number of posts using this camera
`top_posts`	array[catalog post]	highest scoring posts, only when top_posts is set
`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)
`slug`	string	url name (e.g., kodak-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
`top_posts`	array[catalog post]	highest scoring posts, only when top_posts is set
`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_url`	string	path of the next page, relative to /v1
`seed`	integer	random seed used for random sorting

Search Result

The search result resource is returned by both search endpoints.

field name	type	description
`meta`	object	page_size, next_cursor and next_page_url, as in meta
`posts`	array[post]	matching posts
`related_keywords`	array[string]	keywords related to the search, first page only

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. color ranks by how much of the given colors a post has, or gives a rainbow when no color is set	time	time, score, random, color
`page_size`	maximum number of posts returned	20	1-200
`cursor`	cursor of page to retrieve, from next_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`	filter nsfw (18+) posts (true=only, false=exclude)
`grayscale`	filter grayscale (black & white) posts (true=only, false=exclude)
`sprocket`	filter sprocket posts (true=only, false=exclude)
`keyword`	filter by keyword, repeat to require every keyword (e.g., keyword=beach&keyword=sunset)
`color`	filter by color name (red, orange, tan, yellow, green, olive, teal, navy, purple, pink, gray, black, white, brown) or 6 digit hex (e.g., c0392b), repeat to require every color
`min_color`	minimum share of the image from 0 to 1 for each color, paired by position with color. Each color has a default, divided by the number of colors
`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. Results are a single page.

param	description	options
`page_size`	maximum number of similar posts to return	1-50 (default: 12)
`nsfw`	filter nsfw (18+) posts (true=only, false=exclude)	boolean
`grayscale`	filter grayscale (black & white) posts (true=only, false=exclude)	boolean
`sprocket`	filter sprocket posts (true=only, false=exclude)	boolean

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

/search

Returns a search result of posts matching a text query, searching image content, keywords, captions and titles together. Paginated with cursor.

param	description	options
`q`	search text (required)	1-200 characters
`page_size`	number of posts per page	1-100 (default: 50)
`cursor`	cursor of page to retrieve, from next_cursor	string
`nsfw`	filter nsfw (18+) posts (true=only, false=exclude)	boolean
`grayscale`	filter grayscale (black & white) posts (true=only, false=exclude)	boolean
`sprocket`	filter sprocket posts (true=only, false=exclude)	boolean

curl 'https://api.analogdb.com/v1/search?q=girl+at+sunset&grayscale=false'

/search/image

A POST that returns a search result of posts that look like an uploaded image. Results are a single page.

param	description	options
`image`	image to search with, as multipart form data (required)	JPEG, PNG, WebP up to 5 MB
`page_size`	number of posts to return	1-100 (default: 50)
`nsfw`	filter nsfw (18+) posts (true=only, false=exclude)	boolean
`grayscale`	filter grayscale (black & white) posts (true=only, false=exclude)	boolean
`sprocket`	filter sprocket posts (true=only, false=exclude)	boolean

curl -F [email protected] 'https://api.analogdb.com/v1/search/image?page_size=20'

/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	1-1000
`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
`min_count`	only return entries with at least this many posts, implies include_counts	integer
`top_posts`	attach this many top scoring posts to each entry	1-10

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	1-1000
`make`	filter by film make	string
`type`	filter by film type	string
`speed`	filter by film speed	integer
`colortype`	filter by color type (the color_type field)	string
`id`	filter by specific film ID	integer
`include_counts`	include post counts	boolean
`exclude_zero_counts`	exclude films with zero post counts	boolean
`min_count`	only return entries with at least this many posts, implies include_counts	integer
`top_posts`	attach this many top scoring posts to each entry	1-10

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

/keyword/:word

Returns the post count of one keyword, its top_posts as catalog post resources and related keywords that often appear with it. URL encode the word.

param	description	options
`top_posts`	number of top scoring posts	1-10 (default: 6)
`related`	number of related keywords	0-30 (default: 12)

curl https://api.analogdb.com/v1/keyword/beach?related=6

/keywords/summary

Returns the most common keywords, each with a word and post count.

param	description	options
`page_size`	number of keywords to return	1-500 (default: 50)
`days`	only count posts created in the last days	1-90
`min_count`	only return keywords on at least this many posts	integer
`top_posts`	attach this many top scoring posts to each keyword	1-10

curl 'https://api.analogdb.com/v1/keywords/summary?page_size=20&days=30'