Image Collection API Documentation - Version 1

Resources - Photograph (Photographs)

Photographs represent meta-data and references to representations of a single image within the Image Collection.

Resource model

Name Property Name Data Type Optional Description
ID id Integer No Unique identifier
Season season String Yes The date a photograph was taken accurate to a BAS field season, this is suitable as a filter but is not a substitute for a date
Date taken date_taken Date Yes The date a photograph was taken accurate to a day
Caption caption String Yes Free form description of a photograph’s contents
Keywords keywords Array - of - String No List of free form, non-controlled keywords, keywords may not be consistent and are subject to alternate spellings, omissions and errors
Orientation Orientation String Yes A value of either “landscape”, “portrait” or “square” as determined by the mathematical dimensions of the photograph image
Copyright copyright String No The category of copyright holder of a photograph, see [1] for how to use and display this property
Photographer photographer Photographer Yes Each photograph can have a single photographer represented by a Photographer object
Display sizes display_sizes Array - of - Display Size Yes Each photograph can have an array of images at various sizes represented as Display Size’s
Categories categories Array - of - Category Yes Each photograph can have a single category represented as an array of Category’s, see [2] for details
Links links Array - of - Link No Each photograph can have an array of links to resources or actions represented as Link’s
Credit line credit_line String Yes A pre-formatted string, suitable for display, representing individual that created the photograph, this is not the same as the copyright owner [3]
Contact for image contact_for_image Boolean No A flag to indicate an image isn’t available through usual purchasing channels and enquires must therefore be made with BAS separately
Allowed usage allowed_usage Allowed Usage Yes Each photograph can have a set of permissions under which an instance of a photograph can be used, represented as a Allowed Usage
Max width max_width Integer Yes The width of the highest resolution representation of an image measured in pixels, this representation may or may not be available for use
Max height max_height Integer Yes The height of the highest resolution representation of an image measured in pixels, this representation may or may not be available for use
Location freeform location_freeform Location No Each photograph can have a single free form (i.e. uncontrolled) location represented as a Location, see [4] for details

[1] The copyright field will contain the type of copyright holder for a photograph. In some cases this type will also be the actual holder, for others you will need to refer to another property for the actual holder.

This table lists the possible values copyright can be and how to then determine who the copyright holder is.

copyright property value What to use as the copyright holder
British Antarctic Survey “British Antarctic Survey”
Copyright held by photographer Use the photographer’s name (i.e. “photographer.name_first photographer.name_last”)

[2] A photograph is assigned to a single category. Categories are hierarchical using a parent/child relationship. The API will return the photograph’s category and all of its ancestors upto and including the root category.

This is done to increase flexibility, without having to make additional API requests, depending on whether you want to show only the category directly associated with a photograph or construct a breadcrumb to show the categories above the directly associated category.

Categories are represented as a an array with the directly associated category at index 0 with each ancestor as the next index (i.e. the ancestor of the associated category is index 1). The ancestry of categories can also be determined using the id and parent_id fields present in a Category.

[3] The individual that created a photograph (i.e. the photographer) and the entity that holds the copyright for a photograph are two distinct properties and may not always be the same. To distinguish between this, the copyright property will always represent the copyright holder for a photograph and the credit_line property its creator (photographer).

Circumstance and context will determine which of these properties is the most aphrodite to display. In general if you are referring to the owner of a photograph you should display its copyright holder, if you are referring to the photographer or artist the creator (photographer) should be displayed. If only one value can be shown the copyright owner should be displayed.

[4] It is not recommended to use the latitude/longitude values for free text locations as they are not reliable.

Example (JSON)

{
    "data": {
        "id": 10000031,
        "season": "1993/199",
        "date_taken": "1994-01-01",
        "caption": "SANAE III  jackable Summer Accommodation Facility. Scaffold type structure - modular.   Living units on top platform are modified ISO units - again modular & interconnected. In use during summer for building work on SANAE III and to house extra staff  on site during consturction of the new inland station  SANAE IV.",
        "keywords": [
            "Antarctica building station South Africa international"
        ],
        "orientation": "Landscape",
        "copyright": "Copyright held by photographer",
        "photographer": {
            "id": 105,
            "name_last": "Hall",
            "name_first": "John"
        },
        "display_sizes": [
            {
                "name": "small",
                "watermarked": false,
                "width": 218,
                "height": 142,
                "mime-type": "image/jpeg",
                "href": "http://www.photo.antarctica.ac.uk/external/guest/photo/small/53616c7465645f5f36c38388fef565171cdfed939421b6a716abab575edc5f64.jpg"
            },
            {
                "name": "medium",
                "watermarked": false,
                "width": 350,
                "height": 227,
                "mime-type": "image/jpeg",
                "href": "http://www.photo.antarctica.ac.uk/external/guest/photo/medium/53616c7465645f5f7cbf54992b29d286894c523c6c22cbe190dba05d28390698.jpg"
            },
            {
                "name": "large",
                "watermarked": true,
                "width": 540,
                "height": 351,
                "mime-type": "image/jpeg",
                "href": "http://www.photo.antarctica.ac.uk/external/guest/photo/large/53616c7465645f5f3c1b5238f31f35a7072fb15766714a43428c3d790280f4a8.jpg"
            },
            {
                "name": "extra-large",
                "watermarked": false,
                "width": 1280,
                "height": 831,
                "mime-type": "image/jpeg",
                "href": "http://www.photo.antarctica.ac.uk/external/guest/photo/extra-large/53616c7465645f5f3c1b5238f31f35a7072fb15766714a43428c3d790280f4a8.jpg"
            }
        ],
        "categories": [
            {
                "id": 87,
                "parent_id": 86,
                "name": "Station - International"
            },
            {
                "id": 86,
                "parent_id": 0,
                "name": "Research Stations"
            }
        ],
        "links": [
            {
                "type": "website",
                "action": "view",
                "slug": "bas_image_collection",
                "label": "BAS Image Collection",
                "href": "http://www.photo.antarctica.ac.uk/external/guest/detail/search/10000031"
            },
            {
                "type": "website",
                "action": "purchase",
                "slug": "bas_image_collection",
                "label": "BAS Image Collection",
                "href": "http://www.photo.antarctica.ac.uk/external/guest/detail/search/10000031"
            }
        ],
        "credit_line": "John Hall (British Antarctic Survey)",
        "contact_for_image": true,
        "allowed_usage": {
            "description_plain": "Available for all Permitted Uses subject to our License Terms",
            "href_license_terms": "http://www.photo.antarctica.ac.uk/external/guest/tandc_disp",
            "permitted_uses": [
                "Within single Web site only"
            ]
        },
        "max_width": 3697,
        "max_height": 2400,
        "location_freeform": {
            "description": "SANAE III Station  Fimbul Ice Shelf, Dronning Maud Land.",
            "latitude": "70 18 S",
            "longitude": "02 25 W"
        }
    }
}

Resource methods

[GET]/photographs

Returns a listing of all photographs, ordered by their ID in descending order.

Includes a meta array containing the number of resources returned.

Traits
Trait Enabled
Authenticated Yes
Hard limit No
Parameters

None.

Options

None.

Example request

URL: https://api.bas.ac.uk/image-collection/v1/photographs

Note: Interactive examples of this method may be covered in the examples document.

Headers
Key Value
Content-Type application/json
Accept application/json
Body (Raw)

N/A

Example request (200 OK)
Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body (JSON)

Note: For brevity, only the first and last records are shown.

{
    "data": [
        {
            "id": "10000001"
        },
        ...
        {
            "id": "10010672"
        }
    ],
    "meta": {
        "count": 9240
    }
}

[GET]/photographs/{id}

Returns a specified Photograph by its ID.

Traits
Trait Enabled
Authenticated Yes
Hard limit No
Parameters
Name Field Name Data Type Required Valid Value(s) Description
ID {id} Integer Yes A photograph->id Used to specify which photograph to return
Options

None.

Example request

URL: https://api.bas.ac.uk/image-collection/v1/photographs/10000031

Note: Interactive examples of this method may be covered in the examples document.

Headers
Key Value
Content-Type application/json
Accept application/json
Body (Raw)

N/A

Example request (200 OK)
Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body (JSON)
{
    "data": {
        "id": 10000031,
        "season": "1993/199",
        "date_taken": "1994-01-01",
        "caption": "SANAE III  jackable Summer Accommodation Facility. Scaffold type structure - modular.   Living units on top platform are modified ISO units - again modular & interconnected. In use during summer for building work on SANAE III and to house extra staff  on site during consturction of the new inland station  SANAE IV.",
        "keywords": [
            "Antarctica building station South Africa international"
        ],
        "orientation": "Landscape",
        "copyright": "Copyright held by photographer",
        "photographer": {
            "id": 105,
            "name_last": "Hall",
            "name_first": "John"
        },
        "display_sizes": [
            {
                "name": "small",
                "watermarked": false,
                "width": 218,
                "height": 142,
                "mime-type": "image/jpeg",
                "href": "http://www.photo.antarctica.ac.uk/external/guest/photo/small/53616c7465645f5f36c38388fef565171cdfed939421b6a716abab575edc5f64.jpg"
            },
            {
                "name": "medium",
                "watermarked": false,
                "width": 350,
                "height": 227,
                "mime-type": "image/jpeg",
                "href": "http://www.photo.antarctica.ac.uk/external/guest/photo/medium/53616c7465645f5f7cbf54992b29d286894c523c6c22cbe190dba05d28390698.jpg"
            },
            {
                "name": "large",
                "watermarked": true,
                "width": 540,
                "height": 351,
                "mime-type": "image/jpeg",
                "href": "https://www.photo.antarctica.ac.uk/external/guest/photo/large/53616c7465645f5f3c1b5238f31f35a7072fb15766714a43428c3d790280f4a8.jpg"
            },
            {
                "name": "extra-large",
                "watermarked": false,
                "width": 1280,
                "height": 831,
                "mime-type": "image/jpeg",
                "href": "http://www.photo.antarctica.ac.uk/external/guest/photo/extra-large/53616c7465645f5f3c1b5238f31f35a7072fb15766714a43428c3d790280f4a8.jpg"
            }
        ],
        "categories": [
            {
                "id": 87,
                "parent_id": 86,
                "name": "Station - International"
            },
            {
                "id": 86,
                "parent_id": 0,
                "name": "Research Stations"
            }
        ],
        "links": [
            {
                "type": "website",
                "action": "view",
                "slug": "bas_image_collection",
                "label": "BAS Image Collection",
                "href": "http://www.photo.antarctica.ac.uk/external/guest/detail/search/10000031"
            },
            {
                "type": "website",
                "action": "purchase",
                "slug": "bas_image_collection",
                "label": "BAS Image Collection",
                "href": "http://www.photo.antarctica.ac.uk/external/guest/detail/search/10000031"
            }
        ],
        "credit_line": "John Hall (British Antarctic Survey)",
        "contact_for_image": true,
        "allowed_usage": {
            "description_plain": "Available for all Permitted Uses subject to our License Terms",
            "href_license_terms": "http://www.photo.antarctica.ac.uk/external/guest/tandc_disp",
            "permitted_uses": [
                "Within single Web site only"
            ]
        },
        "max_width": 3697,
        "max_height": 2400,
        "location_freeform": {
            "description": "SANAE III Station  Fimbul Ice Shelf, Dronning Maud Land.",
            "latitude": "70 18 S",
            "longitude": "02 25 W"
        }
    }
}
Example request (404 Not Found)

Using URL: https://api.bas.ac.uk/image-collection/v1/photographs/does-not-exist.

Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body (JSON)
{
    "errors": [
        {
            "details": {
                "model_reference_error": {
                    "photograph": [
                        "No photograph could be found with an id of: [does-not-exist]."
                    ]
                }
            },
            "resolution": "Ensure you are providing a valid photograph id.",
            "type": "model_not_found"
        }
    ]
}

Note: The format of this error will change in future API versions (to standardise against the json:api spec.

This information may be out of date whilst this website is being redeveloped. Until then, if you have any problems using an API documented here, please contact the relevant project maintainer.