API Modules

The fathomnet-py API is provided via the fathomnet.api package, and is broken into separate modules for the various FathomNet REST servlets.

Bounding Boxes

The fathomnet.api.boundingboxes module supports bounding box operations.

Create, update, & delete

fathomnet.api.boundingboxes.create_with_dto(bounding_box: BoundingBoxDTO, auth_header: AuthHeader | None = None) → BoundingBoxDTO: Create a bounding box.

fathomnet.api.boundingboxes.update(uuid: str, bounding_box: ABoundingBoxDTO, auth_header: AuthHeader | None = None) → BoundingBoxDTO: Update a bounding box.

fathomnet.api.boundingboxes.delete(uuid: str, auth_header: AuthHeader | None = None): Delete a bounding box.

Bulk create

fathomnet.api.boundingboxes.upload_csv(csv_fp: BinaryIO, auth_header: AuthHeader | None = None) → Message: Upload a CSV of bounding boxes.

Find

fathomnet.api.boundingboxes.find_by_user_defined_key(user_defined_key: str) → List[BoundingBoxDTO]: Get a list of bounding boxes by a user-defined key.

fathomnet.api.boundingboxes.find_by_uuid(uuid: str) → BoundingBoxDTO: Get a bounding box by UUID.

List & count

fathomnet.api.boundingboxes.find_concepts() → List[str]: Get a list of all concepts.

fathomnet.api.boundingboxes.find_observers() → List[str]: Get a list of all observers.

fathomnet.api.boundingboxes.find_all_user_defined_keys() → List[str]: Get a list of all user-defined keys.

fathomnet.api.boundingboxes.count_all() → Count: Get a count of all bounding boxes.

fathomnet.api.boundingboxes.count_by_concept(concept: str) → ByConceptCount: Get a count of bounding boxes for a concept.

fathomnet.api.boundingboxes.count_total_by_concept() → List[ByConceptCount]: Get a count of bounding boxes for each concept.

Audit

fathomnet.api.boundingboxes.audit_by_uuid(uuid: str) → List[BoundingBoxDTO]: Get an audit of a bounding box by UUID.

fathomnet.api.boundingboxes.audit_by_user_defined_key(user_defined_key: str) → List[BoundingBoxDTO]: Get an audit of a bounding box by user-defined key.

Darwin Core

The fathomnet.api.darwincore module supports owner institution darwin core operations.

Note

The darwincore servlet is WIP; This subsection may be updated as new functionality is added.

fathomnet.api.darwincore.find_owner_institution_codes() → List[str]: Get a list of owner institutions.

fathomnet.api.darwincore.find_owner_institutions_by_image_uuid(image_uuid: str) → List[str]: Get a list of owner institutions by image UUID.

fathomnet.api.darwincore.index() → str: Get the darwin core index page.

Firebase

The fathomnet.api.firebase module supports firebase authentication operations.

Warning

The firebase servlet that this module wraps is designed for application-level authentication. Typical users will not need to use this module.

fathomnet.api.firebase.auth() → AuthHeader: Authenticate via firebase and get a JWT.

fathomnet.api.firebase.test(auth_header: AuthHeader | None = None) → Message: Test an authorization token.

Geo-images

The fathomnet.api.geoimages module supports geo-image operations.

fathomnet.api.geoimages.count(geo_image_constraints: GeoImageConstraints) → GeoImageConstraintsCount: Get a constrained count of geo images.

fathomnet.api.geoimages.find(geo_image_constraints: GeoImageConstraints) → List[GeoImage]: Get a constrained list of geo images.

fathomnet.api.geoimages.find_all(pageable: Pageable | None = None) → List[GeoImage]: Get a paged list of all geo images.

fathomnet.api.geoimages.find_by_image_set_upload_uuid(image_set_upload_uuid: str, limit: int | None = None, offset: int | None = None) → List[GeoImage]: Get a list of geo images corresponding to an image set upload UUID.

Images

The fathomnet.api.images module supports image operations.

Create, update, & delete

fathomnet.api.images.create_if_not_exists(images: List[Image], auth_header: AuthHeader | None = None) → List[AImageDTO]: Create an image if it doesn’t exist.

fathomnet.api.images.update(uuid: str, image: AImageDTO, auth_header: AuthHeader | None = None) → AImageDTO: Update an image.

fathomnet.api.images.delete(uuid: str, auth_header: AuthHeader | None = None): Delete an image.

Find

fathomnet.api.images.find(geo_image_constraints: GeoImageConstraints) → List[AImageDTO]: Get a constrained list of images.

fathomnet.api.images.find_all(pageable: Pageable | None = None) → List[AImageDTO]: Get a paged list of all images.

fathomnet.api.images.find_all_alt(pageable: Pageable | None = None) → List[AImageDTO]: Get a paged list of all images. (alternative endpoint)

fathomnet.api.images.find_by_concept(concept: str, taxa: str | None = None) → List[AImageDTO]: Get a list of images by concept (and optionally taxa provider).

fathomnet.api.images.find_by_contributors_email(contributors_email: str) → List[AImageDTO]: Get a list of images by contributor.

fathomnet.api.images.find_by_observer(observer: str) → List[AImageDTO]: Get a list of images by observer.

fathomnet.api.images.find_by_sha256(sha256: str) → List[AImageDTO]: Get a list of images by SHA256 hash.

fathomnet.api.images.find_by_tag_key(key: str, value: str) → List[AImageDTO]: Get a list of images by a specified tag key-value pair.

fathomnet.api.images.find_by_url(url: str) → AImageDTO: Get an image by URL.

fathomnet.api.images.find_by_uuid(uuid: str) → AImageDTO: Get an image by UUID.

fathomnet.api.images.find_by_uuid_in_list(uuids: List[str]) → List[AImageDTO]: Get a list of images corresponding to a specified list of UUIDs.

List & count

fathomnet.api.images.find_distinct_submitter() → List[str]: Get a list of all submitters.

fathomnet.api.images.list_imaging_types() → List[str]: Get a list of all imaging types.

fathomnet.api.images.count_all() → Count: Get a count of all images.

fathomnet.api.images.count_by_submitter(contributors_email: str) → ByContributorCount: Get a count of images by contributor.

Image Set Uploads

The fathomnet.api.imagesetuploads module supports image set upload operations.

Find

fathomnet.api.imagesetuploads.find_collections(pageable: Pageable | None = None) → List[BImageSetUploadDTO]: Get a paged list of all image set uploads.

fathomnet.api.imagesetuploads.find_by_image_uuid(image_uuid: str) → List[BImageSetUploadDTO]: Get an image set upload by UUID.

fathomnet.api.imagesetuploads.find_by_contributor(contributors_email: str) → List[BImageSetUploadDTO]: Get a list of image set uploads by contributor.

fathomnet.api.imagesetuploads.find_by_uuid(uuid: str) → BImageSetUploadDTO: Get an image set upload by UUID.

List & count

fathomnet.api.imagesetuploads.find_rejection_reasons() → List[str]: Get a list of all rejection reasons.

fathomnet.api.imagesetuploads.find_contributors() → List[str]: Get a list of all contributors.

fathomnet.api.imagesetuploads.count_all() → Count: Count all image set uploads.

Compute stats

fathomnet.api.imagesetuploads.stats(image_set_upload_uuid: str) → ImageSetUploadStats: Get image set upload statistics for a corresponding image set upload UUID.

Regions

The fathomnet.api.regions module supports marine region operations.

fathomnet.api.regions.count_all() → int: Get a count of all marine regions.

fathomnet.api.regions.find_all() → List[MarineRegion]: Get a list of all marine regions.

fathomnet.api.regions.find_all_paged(pageable: Pageable | None) → List[MarineRegion]: Get a paged list of all marine regions.

fathomnet.api.regions.find_at(latitude: float, longitude: float) → List[MarineRegion]: Get the marine regions at the given latitude and longitude.

fathomnet.api.regions.sync(auth_header: AuthHeader | None = None) → int: Synchronize.

Stats

The fathomnet.api.stats module supports summary statistic operations.

fathomnet.api.stats.contribution_stats() → List[ContributionStats]: Get contribution stats by contributing institution.

fathomnet.api.stats.image_set_upload_positions() → List[ImageSetUploadPosition]: Get a list of image set upload positions.

fathomnet.api.stats.most_popular_searches() → List[str]: Get a list of the most popular searches.

Tags

Note

Tags API added in v0.4.0

The fathomnet.api.tags module supports tag operations.

Create, update, & delete

fathomnet.api.tags.create_with_dto(tag: TagDTO, auth_header: AuthHeader | None = None) → TagDTO: Create a tag.

fathomnet.api.tags.update(uuid: str, tag: TagDTO, auth_header: AuthHeader | None = None) → TagDTO: Update a tag.

fathomnet.api.tags.delete(uuid: str, auth_header: AuthHeader | None = None): Delete a tag.

Find

fathomnet.api.tags.find_by_uuid(uuid: str) → TagDTO: Get a tag by UUID.

fathomnet.api.tags.find_by_image_uuid_and_key(image_uuid: str, key: str) → List[TagDTO]: Get a tag by image UUID and key.

Taxa

The fathomnet.api.taxa module supports taxonomic (phylogenic) lookup operations.

fathomnet.api.taxa.find_children(provider_name: str, concept: str) → List[Taxa]: Find the taxonomic children for a concept according to a taxa provider.

fathomnet.api.taxa.find_parent(provider_name: str, concept: str) → Taxa: Find the taxonomic parent for a concept according to a taxa provider.

fathomnet.api.taxa.find_taxa(provider_name: str, concept: str) → List[Taxa]: Get a list of all taxonomic descendants of a concept (including the concept itself) according to a taxa provider.

fathomnet.api.taxa.list_taxa_providers() → List[str]: Get a list of all taxa providers.

Users

The fathomnet.api.users module supports user account operations.

Account operations

fathomnet.api.users.create_new_api_key(auth_header: AuthHeader | None = None) → ApiKey: Create a new API key for a user.

fathomnet.api.users.delete_api_key(auth_header: AuthHeader | None = None): Delete a user’s API key.

fathomnet.api.users.update_user_data(fathomnet_id_mutation: FathomnetIdMutation, auth_header: AuthHeader | None = None) → FathomnetIdentity: Update a user’s account data.

List & count

fathomnet.api.users.find_all(pageable: Pageable | None = None, auth_header: AuthHeader | None = None) → List[FathomnetIdentity]: Get a paged list of all users.

fathomnet.api.users.find_by_authentication(auth_header: AuthHeader | None = None) → FathomnetIdentity: Find a user by authentication.

fathomnet.api.users.find_by_email(email: str, auth_header: AuthHeader | None = None) → FathomnetIdentity: Find a user by email.

fathomnet.api.users.find_by_firebase_uid(uid: str, auth_header: AuthHeader | None = None) → FathomnetIdentity: Find a user by Firebase UID.

fathomnet.api.users.find_contributors_names() → List[str]: Get a list of all contributor names.

fathomnet.api.users.find_expertise() → List[str]: Get a list of all expertise levels.

fathomnet.api.users.find_roles() → List[str]: Get a list of all user roles.

fathomnet.api.users.count_all() → Count: Get a count of all users.

Miscellaneous

fathomnet.api.users.get_api_key(auth_header: AuthHeader | None = None) → ApiKey: Get a user’s API key.

fathomnet.api.users.verify(auth_header: AuthHeader | None = None) → Authentication: Get the contents of an authorization token.

Admin only

fathomnet.api.users.disable_by_uuid(uuid: str, auth_header: AuthHeader | None = None): (Admin) Disable an account by its UUID.

fathomnet.api.users.update_user_data_admin(uuid: str, fathomnet_id_admin_mutation: FathomnetIdAdminMutation, auth_header: AuthHeader | None = None) → FathomnetIdentity: (Admin) Update a user’s account data.

WoRMS

The fathomnet.api.worms module supports World Register of Marine Species (WoRMS) lookup operations via the fast WoRMS name service.

fathomnet.api.worms.count_names() → int: Get the total number of names available.

fathomnet.api.worms.find_names_by_prefix(prefix: str) → List[str]: Get all names that start with a prefix.

fathomnet.api.worms.find_names_containing(fragment: str) → List[str]: Get all names that contain a fragment.

fathomnet.api.worms.find_taxa_by_prefix(prefix: str, rank: str = None, parent: str = None) → List[WormsNode]: Get all taxa nodes that start with a prefix.

fathomnet.api.worms.get_all_names(limit: int = 100, offset: int = 0) → List[str]: Get all names.

fathomnet.api.worms.get_ancestors(name: str) → WormsNode: Get a taxa tree from the root node to the node for the given name.

fathomnet.api.worms.get_ancestors_names(name: str) → List[str]: Get all ancestors’ names of a given name.

fathomnet.api.worms.get_children(name: str) → List[WormsNode]: Get the child taxa nodes of a given name.

fathomnet.api.worms.get_children_names(name: str) → List[str]: Get all children’s names of a given name.

fathomnet.api.worms.get_descendants(name: str) → WormsNode: Get a taxa tree from the given name to the leaves.

fathomnet.api.worms.get_descendants_names(name: str, accepted: bool = False) → List[str]: Get all descendants’ names of a given name.

fathomnet.api.worms.get_info(name: str) → WormsNode: Get a taxa node for a given name.

fathomnet.api.worms.get_names_by_aphia_id(aphia_id: int) → WormsNames: Get the names data for a given Aphia ID.

fathomnet.api.worms.get_parent(name: str) → WormsNode: Get the parent taxa node of a given name.

fathomnet.api.worms.get_parent_name(name: str) → str: Get the parent’s name of a given name.

fathomnet.api.worms.get_synonyms_for_name(name: str) → List[str]: Get all synonyms for a name.

fathomnet.api.worms.get_worms_api_url() → str

Get the Fast WoRMS API URL from the FATHOMNET_WORMS_API_URL environment variable or use the default value.

Returns:: str: The Fast WoRMS API base URL.

X-API-Key

The fathomnet.api.xapikey module supports X-API-Key authentication operations.

fathomnet.api.xapikey.auth(api_key: str) → AuthHeader: Exchange an API key for a JWT.

fathomnet.api.xapikey.index(auth_header: AuthHeader | None = None): Test a JWT to ensure it’s valid.