API
This page provides a detailed description of every class and function provided by the lomography module. It is seperated into two sections: the synchronous API and the asynchronous API. The synchronous API is a thin wrapper around the asynchronous API, which is based on the aiohttp library. The synchronous API is provided for convenience and ease of use, while the asynchronous API is provided for performance and scalability.
Synchronous API
- class lomography.Lomography(api_key: str, loop: AbstractEventLoop | None = None)
This class provides a synchronous Python interface for the Lomography API, designed to facilitate access to photographic content, camera and film data, and user information. The API offers methods to fetch popular and recent photos, as well as specific photos taken by certain cameras or films, and supports pagination to navigate through larger datasets.
- Example Usage:
>>> lomo = Lomography(api_key="your_api_key_here") >>> popular_photos = lomo.fetch_popular_photos(amt=15)
More information can be found in the Lomography API documentation at https://api.lomography.com.
- __init__(api_key: str, loop: AbstractEventLoop | None = None)
- Parameters:
api_key (str) – The API key for authentication to access the Lomography API.
loop (asyncio.AbstractEventLoop) – An optional event loop to use for asynchronous operations. If not provided, a self-managed event loop will be created and maintained by the class.
- close()
Synchronously close the session by running the asynchronous close method and then close the event loop if it was created by this instance.
- Parameters:
None – No parameters.
- Returns:
None.
- fetch_camera_by_id(camera_id: int)
Fetch a specific camera by its unique ID.
- Parameters:
camera_id (int) – The unique ID of the camera to retrieve.
- Returns:
A LomoCamera object representing the camera.
- Return type:
- fetch_cameras(amt: int = 20, index: int = 0)
Fetch a list of cameras available.
- Parameters:
- Returns:
A list of LomoCamera objects representing the cameras.
- Return type:
List[LomoCamera]
- fetch_photos_near_point(latitude: float, longitude: float, dist: int = 10, amt: int = 20, index: int = 0)
Fetch photos near a specific geographic point within a given distance.
- Parameters:
latitude (float) – The latitude of the geographic point.
longitude (float) – The longitude of the geographic point.
dist (int) – The distance (in kilometers) around the point to include photos from. Defaults to 10 km.
amt (int) – The number of photos to retrieve. Defaults to 20.
index (int) – The zero-based index from which to start the photo retrieval within the result set. Defaults to 0.
- Returns:
A list of LomoPhoto objects representing the photos.
- Return type:
List[LomoPhoto]
- fetch_popular_photos(amt: int = 20, index: int = 0)
Fetch the most popular photos uploaded in the last month. This method utilizes a predefined API endpoint function to fetch photos that have been identified as the most popular over the last month based on views or likes.
- fetch_popular_photos_by_camera_id(camera_id: int, amt: int = 20, index: int = 0)
Fetch popular photos taken with a specific camera. This method returns the most popular photos (uploaded in the last month) taken with that camera.
- Parameters:
- Returns:
A list of LomoPhoto objects representing the popular photos.
- Return type:
List[LomoPhoto]
- fetch_popular_photos_by_film_id(film_id: int, amt: int = 20, index: int = 0)
Fetch popular photos taken with a specific film. This will return the most popular photos (uploaded in the last month) taken with that film.
- Parameters:
- Returns:
A list of LomoPhoto objects representing the popular photos.
- Return type:
List[LomoPhoto]
- fetch_popular_photos_near_point(latitude: float, longitude: float, dist: int = 10, amt: int = 20, index: int = 0)
Fetch popular photos near a specific geographic point within a given distance, based on popularity.
- Parameters:
latitude (float) – The latitude of the geographic point.
longitude (float) – The longitude of the geographic point.
dist (int) – The distance (in kilometers) around the point to include photos from. Defaults to 10 km.
amt (int) – The number of photos to retrieve. Defaults to 20.
index (int) – The zero-based index from which to start the photo retrieval within the result set. Defaults to 0.
- Returns:
A list of LomoPhoto objects representing the popular photos.
- Return type:
List[LomoPhoto]
- fetch_popular_photos_within_bounding_box(latitude_north: float, longitude_east: float, latitude_south: float, longitude_west: float, amt: int = 20, index: int = 0)
Fetch popular photos within a specified bounding box.
- Parameters:
latitude_north (float) – The northern latitude of the bounding box.
longitude_east (float) – The eastern longitude of the bounding box.
latitude_south (float) – The southern latitude of the bounding box.
longitude_west (float) – The western longitude of the bounding box.
amt (int) – The number of photos to retrieve. Defaults to 20.
index (int) – The zero-based index from which to start the photo retrieval within the result set. Defaults to 0.
- Returns:
A list of LomoPhoto objects representing the popular photos.
- Return type:
List[LomoPhoto]
- fetch_recent_photos(amt: int = 20, index: int = 0)
Fetch the most recent photos (right as they are uploaded). This method calls a function to retrieve the latest photos added to the platform, reflecting the most current content available.
- fetch_recent_photos_by_camera_id(camera_id: int, amt: int = 20, index: int = 0)
Fetch recent photos taken with a specific camera. This method returns the most recent photos (right as they are uploaded) taken with that camera.
- Parameters:
- Returns:
A list of LomoPhoto objects representing the recent photos.
- Return type:
List[LomoPhoto]
- fetch_recent_photos_by_film_id(film_id: int, amt: int = 20, index: int = 0)
Fetch recent photos taken with a specific film. This will return the most recent photos (right as they are uploaded) taken with that film.
- Parameters:
- Returns:
A list of LomoPhoto objects representing the recent photos.
- Return type:
List[LomoPhoto]
- fetch_recent_photos_near_point(latitude: float, longitude: float, dist: int = 10, amt: int = 20, index: int = 0)
Fetch recent photos near a specific geographic point within a given distance.
- Parameters:
latitude (float) – The latitude of the geographic point.
longitude (float) – The longitude of the geographic point.
dist (int) – The distance (in kilometers) around the point to include photos from. Defaults to 10 km.
amt (int) – The number of photos to retrieve. Defaults to 20.
index (int) – The zero-based index from which to start the photo retrieval within the result set. Defaults to 0.
- Returns:
A list of LomoPhoto objects representing the recent photos.
- Return type:
List[LomoPhoto]
- fetch_recent_photos_within_bounding_box(latitude_north: float, longitude_east: float, latitude_south: float, longitude_west: float, amt: int = 20, index: int = 0)
Fetch recent photos within a specified bounding box.
- Parameters:
latitude_north (float) – The northern latitude of the bounding box.
longitude_east (float) – The eastern longitude of the bounding box.
latitude_south (float) – The southern latitude of the bounding box.
longitude_west (float) – The western longitude of the bounding box.
amt (int) – The number of photos to retrieve. Defaults to 20.
index (int) – The zero-based index from which to start the photo retrieval within the result set. Defaults to 0.
- Returns:
A list of LomoPhoto objects representing the recent photos.
- Return type:
List[LomoPhoto]
- fetch_selected_photos(amt: int = 20, index: int = 0)
Fetch a selection of featured photos, curated based on specific criteria like artistic value or themes. This method interfaces with a function designed to pull a curated list of photos that are highlighted for their notable features or thematic focus.
- class lomography.LomoPhoto(lomo: Lomography, data: PhotoDict)
A photo object from Lomography, containing all the necessary information about a photo. This class contains the camera, film, user, lens, tags, and images associated with the photo.
- Variables:
id (int) – The unique identifier for the photo.
title (Optional[str]) – The title of the photo.
description (Optional[str]) – The description of the photo.
url (str) – The URL of the photo.
camera (Optional[LomoCamera]) – The camera used to take the photo.
film (Optional[LomoFilm]) – The film used to take the photo.
user (LomoUser) – The user who uploaded the photo.
small (LomoPhotoImage) – The small version of the photo.
large (LomoPhotoImage) – The large version of the photo.
asset_hash (str) – The hash of the photo asset.
asset_width (int) – The width of the photo asset.
asset_height (int) – The height of the photo asset.
asset_ratio (float) – The aspect ratio of the photo asset.
asset_preview (str) – The preview of the photo asset.
lens (Optional[LomoLens]) – The lens used to take the photo.
tags (List[LomoTag]) – The tags associated with the photo.
- class lomography.LomoCamera(lomo: Lomography, data: CameraDict)
Represents a camera object. This is used to categorize photos, it can include cameras like “Diana F+”, “Lomo LC-A+”, “Holga 120N”, etc. and makes it easier for users to find the photos they are looking for.
- fetch_popular_photos(amt: int = 20, index: int = 0)
Fetch popular photos taken with this camera. This will return the most popular photos (uploaded in the last month) taken with this camera.
- class lomography.LomoFilm(lomo: Lomography, data: FilmDict)
Represents a film object. This is used to categorize photos, it can include films like “Lomography Color Negative 400”, “Lomography Lady Grey 400”, “Lomography X-Pro Slide 200”, etc. and makes it easier for users to find the photos they are looking for.
- class lomography.LomoUser(lomo: Lomography, data: UserDict)
Represents a user object. A user can be a photographer or a member of the Lomography community, and can have a profile image. They can upload photos.
- class lomography.LomoLens(lomo: Lomography, data: LensDict)
Represents a lens object.
- class lomography.LomoTag(lomo: Lomography, data: TagDict)
Represents a tag object. This is used to categorize photos, it can include tags like “portrait”, “landscape”, “black and white”, etc. and makes it easier for users to find the photos they are looking for
Asynchronous API
- class lomography.AsyncLomography(api_key: str)
This class provides an asynchronous Python interface for the Lomography API, designed to facilitate access to photographic content, camera and film data, and user information. The API offers methods to fetch popular and recent photos, as well as specific photos taken by certain cameras or films, and supports pagination to navigate through larger datasets.
- Example Usage:
>>> async_lomo = AsyncLomography(api_key="api_key_here") >>> photos = await async_lomo.fetch_popular_photos(amt=15)
More information can be found in the Lomography API documentation at https://api.lomography.com.
- __init__(api_key: str)
- Parameters:
api_key (str) – The API key for authentication to access the Lomography API.
- async fetch_camera_by_id(camera_id: int)
Asynchronously fetch a specific camera by its unique ID.
- Parameters:
camera_id (int) – The unique ID of the camera to retrieve.
- Returns:
An AsyncLomoCamera object representing the camera.
- Return type:
- async fetch_cameras(amt: int = 20, index: int = 0)
Asynchronously fetch a list of cameras available on the platform.
- Parameters:
- Returns:
A list of AsyncLomoCamera objects representing the cameras.
- Return type:
List[AsyncLomoCamera]
- async fetch_film_by_id(film_id: int)
Asynchronously fetch a specific film by its unique ID.
- Parameters:
film_id (int) – The unique ID of the film to retrieve.
- Returns:
An AsyncLomoFilm object representing the film.
- Return type:
- async fetch_films(amt: int = 20, index: int = 0)
Asynchronously fetch a list of films available on the platform.
- Parameters:
- Returns:
A list of AsyncLomoFilm objects representing the films.
- Return type:
List[AsyncLomoFilm]
- async fetch_photos_near_point(latitude: float, longitude: float, dist: int = 10, amt: int = 20, index: int = 0)
Asynchronously fetch photos near a specific geographic point within a certain distance.
- Parameters:
latitude (float) – The latitude of the point.
longitude (float) – The longitude of the point.
dist (int) – The distance in kilometers around the point to include for photo retrieval. Default is 10 km.
amt (int) – The number of photos to retrieve. Defaults to 20.
index (int) – The zero-based index from which to start the photo retrieval. Defaults to 0.
- Returns:
A list of AsyncLomoPhoto objects representing the photos near the specified point.
- Return type:
List[AsyncLomoPhoto]
- async fetch_popular_photos(amt: int = 20, index: int = 0)
Fetch the most popular photos uploaded in the last month using an asynchronous API endpoint. This method is designed to fetch photos based on views or likes, identifying them as most popular.
- Parameters:
- Returns:
A list of AsyncLomoPhoto objects representing the most popular photos.
- Return type:
List[AsyncLomoPhoto]
- async fetch_popular_photos_by_camera_id(camera_id: int, amt: int = 20, index: int = 0)
Asynchronously fetch popular photos taken with a specific camera, identified based on uploads in the last month.
- Parameters:
- Returns:
A list of AsyncLomoPhoto objects representing the popular photos.
- Return type:
List[AsyncLomoPhoto]
- async fetch_popular_photos_by_film_id(film_id: int, amt: int = 20, index: int = 0)
Asynchronously fetch popular photos taken with a specific film. This method returns the most popular photos uploaded in the last month taken with that film.
- Parameters:
- Returns:
A list of AsyncLomoPhoto objects representing the popular photos.
- Return type:
List[AsyncLomoPhoto]
- async fetch_popular_photos_near_point(latitude: float, longitude: float, dist: int = 10, amt: int = 20, index: int = 0)
Asynchronously fetch popular photos near a specific geographic point. This method focuses on the most popular photos uploaded in the last month within the specified distance.
- Parameters:
latitude (float) – The latitude of the point.
longitude (float) – The longitude of the point.
dist (int) – The distance in kilometers around the point to include for photo retrieval. Default is 10 km.
amt (int) – The number of photos to retrieve. Defaults to 20.
index (int) – The zero-based index from which to start the photo retrieval. Defaults to 0.
- Returns:
A list of AsyncLomoPhoto objects representing the popular photos near the specified point.
- Return type:
List[AsyncLomoPhoto]
- async fetch_popular_photos_within_bounding_box(latitude_north: float, longitude_east: float, latitude_south: float, longitude_west: float, amt: int = 20, index: int = 0)
Asynchronously fetch popular photos within a particular bounding box. This will return the most popular photos (uploaded in the last month).
- Parameters:
latitude_north (float) – The northern latitude of the bounding box.
longitude_east (float) – The eastern longitude of the bounding box.
latitude_south (float) – The southern latitude of the bounding box.
longitude_west (float) – The western longitude of the bounding box.
amt (int) – The number of photos to retrieve. Defaults to 20.
index (int) – The zero-based index from which to start the photo retrieval within the result set. Defaults to 0.
- Returns:
A list of AsyncLomoPhoto objects representing the popular photos.
- Return type:
List[AsyncLomoPhoto]
- async fetch_recent_photos(amt: int = 20, index: int = 0)
Fetch the most recent photos asynchronously, capturing the latest uploads to the platform.
- Parameters:
- Returns:
A list of AsyncLomoPhoto objects representing the most recent photos.
- Return type:
List[AsyncLomoPhoto]
- async fetch_recent_photos_by_camera_id(camera_id: int, amt: int = 20, index: int = 0)
Asynchronously fetch the most recent photos taken with a specific camera, showcasing the latest uploads.
- Parameters:
- Returns:
A list of AsyncLomoPhoto objects representing the recent photos.
- Return type:
List[AsyncLomoPhoto]
- async fetch_recent_photos_by_film_id(film_id: int, amt: int = 20, index: int = 0)
Asynchronously fetch recent photos taken with a specific film. This method returns the most recent photos uploaded, showcasing current content.
- Parameters:
- Returns:
A list of AsyncLomoPhoto objects representing the recent photos.
- Return type:
List[AsyncLomoPhoto]
- async fetch_recent_photos_near_point(latitude: float, longitude: float, dist: int = 10, amt: int = 20, index: int = 0)
Asynchronously fetch recent photos near a particular point in a range. This will return the most recent photos (right as they are uploaded) taken closest to that point.
- Parameters:
latitude (float) – The latitude of the point.
longitude (float) – The longitude of the point.
dist (int) – The range in kilometers to search for photos. Default is 10.
amt (int) – The number of photos to retrieve. Defaults to 20.
index (int) – The zero-based index from which to start the photo retrieval within the result set. Defaults to 0.
- Returns:
A list of AsyncLomoPhoto objects representing the recent photos.
- Return type:
List[AsyncLomoPhoto]
- async fetch_recent_photos_within_bounding_box(latitude_north: float, longitude_east: float, latitude_south: float, longitude_west: float, amt: int = 20, index: int = 0)
Asynchronously fetch recent photos within a particular bounding box. This will return the most recent photos (right as they are uploaded).
- Parameters:
latitude_north (float) – The northern latitude of the bounding box.
longitude_east (float) – The eastern longitude of the bounding box.
latitude_south (float) – The southern latitude of the bounding box.
longitude_west (float) – The western longitude of the bounding box.
amt (int) – The number of photos to retrieve. Defaults to 20.
index (int) – The zero-based index from which to start the photo retrieval within the result set. Defaults to 0.
- Returns:
A list of AsyncLomoPhoto objects representing the recent photos.
- Return type:
List[AsyncLomoPhoto]
- async fetch_selected_photos(amt: int = 20, index: int = 0)
Fetch a selection of featured photos asynchronously, curated based on specific criteria such as artistic value or themes.
- Parameters:
- Returns:
A list of AsyncLomoPhoto objects representing the selected photos.
- Return type:
List[AsyncLomoPhoto]
- class lomography.AsyncLomoPhoto(lomo: AsyncLomography, data: PhotoDict)
An asynchronous photo object from Lomography, containing all the necessary information about a photo. This class contains the camera, film, user, lens, tags, and images associated with the photo.
- Variables:
id (int) – The unique identifier for the photo.
title (Optional[str]) – The title of the photo.
description (Optional[str]) – The description of the photo.
url (str) – The URL of the photo.
camera (Optional[AsyncLomoCamera]) – The camera used to take the photo.
film (Optional[AsyncLomoFilm]) – The film used to take the photo.
user (AsyncLomoUser) – The user who uploaded the photo.
small (LomoPhotoImage) – The small version of the photo.
large (LomoPhotoImage) – The large version of the photo.
asset_hash (str) – The hash of the photo asset.
asset_width (int) – The width of the photo asset.
asset_height (int) – The height of the photo asset.
asset_ratio (float) – The aspect ratio of the photo asset.
asset_preview (str) – The preview of the photo asset.
lens (Optional[AsyncLomoLens]) – The lens used to take the photo.
tags (List[AsyncLomoTag]) – The tags associated with the photo.
- class lomography.AsyncLomoCamera(lomo: AsyncLomography, data: CameraDict)
Represents an asynchronous camera object. This is used to categorize photos, it can include cameras like “Diana F+”, “Lomo LC-A+”, “Holga 120N”, etc. and makes it easier for users to find the photos they are looking for.
- async fetch_popular_photos(amt: int = 20, index: int = 0)
Fetch popular photos taken with this camera. This will return the most popular photos (uploaded in the last month) taken with this camera.
- Parameters:
- Returns:
A list of AsyncLomoPhoto objects representing the popular photos.
- Return type:
List[AsyncLomoPhoto]
- async fetch_recent_photos(amt: int = 20, index: int = 0)
Fetch recent photos taken with this camera. This will return the most recent photos (right as they are uploaded) taken with this camera.
- Parameters:
- Returns:
A list of AsyncLomoPhoto objects representing the recent photos.
- Return type:
List[AsyncLomoPhoto]
- class lomography.AsyncLomoFilm(lomo: AsyncLomography, data: FilmDict)
Represents an asynchronous film object. This is used to categorize photos, it can include films like “Lomography Color Negative 400”, “Lomography Lady Grey 400”, “Lomography X-Pro Slide 200”, etc. and makes it easier for users to find the photos they are looking for.
- async fetch_popular_photos(amt: int = 20, index: int = 0)
Fetch popular photos taken with this film.
- Parameters:
- Returns:
A list of AsyncLomoPhoto objects representing the popular photos.
- Return type:
List[AsyncLomoPhoto]
- async fetch_recent_photos(amt: int = 20, index: int = 0)
Fetch recent photos taken with this film.
- Parameters:
- Returns:
A list of AsyncLomoPhoto objects representing the recent photos.
- Return type:
List[AsyncLomoPhoto]
- class lomography.AsyncLomoUser(lomo: AsyncLomography, data: UserDict)
Represents an asynchronous user object. A user can be a photographer or a member of the Lomography community, and can have a profile image. They can upload photos.
- class lomography.AsyncLomoLens(lomo: AsyncLomography, data: LensDict)
Represents an asynchronous lens object.
- class lomography.AsyncLomoTag(lomo: AsyncLomography, data: TagDict)
Represents an asynchronous tag object. This is used to categorize photos, it can include tags like “portrait”, “landscape”, “black and white”, etc. and makes it easier for users to find the photos they are looking for
Generic API
- class lomography.LomoImage(data: ImageDict)
A class representing an image. This is a generic, base class for all image objects. It can represent a user avatars, actual photo assets, etc.
- class lomography.LomoPhotoImage(data: PhotoImageDict)
A class representing a photo image. This is associated with a LomoPhoto, and usually fits into the small and large attributes of a LomoPhoto object. This is normally not a user profile picture, but an actual asset.