Image Collection API Documentation - Version 1

Methods - Search

[OPTIONS]/search/resources

Returns a list of resources which can be searched upon.

Traits
Trait Enabled
Authenticated Yes
Hard limit No
Parameters

None.

Options

None.

Example request

URL: http://api.bas.ac.uk/image-collection/v1/search/resources

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

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

N/A

Example response (200 OK)
Headers
Key Value
Content-Type application/json
Body (JSON)
{
    "data": {
        "supported_resources": [
            "photographs"
        ]
    }
}

[GET]/search/{resource}/{search-terms}

Returns a listing of all resources whose properties match a number of search terms ordered by their ID in ascending order.

Includes a meta array containing the number of resources returned.

Note: This method is currently quite slow it is therefore recommended to make as focused a search as possible.

Supported resources

See the [OPTIONS]/search/resources method for a list of resources that can be searched.

Search properties by resource

The properties of a resource that are searched against depends on the resource being searched, as detailed below:

Resource Searched Properties (properties separated by ,)
Photograph keywords
Returned entities by resource

Generally, entities of the resource being searched against mirror those of their index method (e.g. /photographs). This means any ordering or grouping used by the index method will also be used by this search method.

For clarity, any such transformations made to particular resources are detailed below:

Resource Transformations applied Do transformations applied match resource index method?
Photograph Entites are ordered by their id in descending order Yes
Traits
Trait Enabled
Authenticated Yes
Hard limit Yes
Parameters
Name Field Name Data Type Required Valid Value(s) Description
Resource {resource} String Yes A supported resource Used to specify which resource to search on
Search terms {search-terms} String Yes A comma separated list of URL encoded search terms [1] Used to specify which search terms to use

[1] Note: If searching on the photographs resource and enter a field season (i.e. 1989/1990) as a search term you must replace forward slashes (/) with hyphens (-). The API will automatically covert these back to slashes when searching.

Options

None.

Example request

URL: https://api.bas.ac.uk/image-collection/v1/search/photographs/rothera,seal

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

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

N/A

Example response (200 OK)
Headers
Key Value
Content-Type application/json
Body (JSON)
{
    "data": [
        {
            "id": 10000601,
            "season": null,
            "date_taken": null,
            "caption": "Basking Weddell Seals (Leptonychotes weddellii) on ice floe",
            "keywords": [
                "Weddell seal",
                "Wildlife",
                "seal",
                "Antarctica",
                "Leptonychotes weddellii ice floe"
            ],
            "orientation": "Landscape",
            "copyright": "Copyright held by photographer",
            "photographer": {
                "id": 217,
                "website": null,
                "name_last": "Paren",
                "name_first": "Julian",
                "organisation_name": null
            },
            "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/53616c7465645f5fdf341cc2624bbdf026cadf5524c1922cdadb29a0cd794018.jpg"
                },
                {
                    "name": "medium",
                    "watermarked": false,
                    "width": 350,
                    "height": 228,
                    "mime_type": "image/jpeg",
                    "href": "http://www.photo.antarctica.ac.uk/external/guest/photo/medium/53616c7465645f5f38228ea37b527fc7ba54b50dd06e82dd1cb41d8670db32b9.jpg"
                },
                {
                    "name": "large",
                    "watermarked": true,
                    "width": 540,
                    "height": 352,
                    "mime_type": "image/jpeg",
                    "href": "http://www.photo.antarctica.ac.uk/external/guest/photo/large/53616c7465645f5f4ce27dd511dcbe96d4f37321677c949aa50db39ca6b136b4.jpg"
                }
                {
                    "name": "extra-large",
                    "watermarked": false,
                    "width": 1280,
                    "height": 835,
                    "mime_type": "image\/jpeg",
                    "href": "http:\/\/www.photo.antarctica.ac.uk\/external\/guest\/photo\/extra-large\/53616c7465645f5f223e92e3b2030ecf2f3717ace02e7f1ccb07f10f1105ba29.jpg"
                }
            ],
            "categories": [
                {
                    "id": 5,
                    "parent_id": 80,
                    "name": "Weddell"
                },
                {
                    "id": 80,
                    "parent_id": 113,
                    "name": "Seal"
                },
                {
                    "id": 113,
                    "parent_id": 0,
                    "name": "Wildlife"
                }
            ],
            "links": [],
            "credit_line": "Julian Paren (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": [
                    "BAS Public website only"
                ]
            },
            "max_width": 3693,
            "max_height": 2408,
            "location_freeform": {
                "description": "North Bay, Rothera Point",
                "latitude": null,
                "longitude": null
            }
        },
        ...
        {
            "id": 10010516,
            "season": "2009/2010",
            "date_taken": null,
            "caption": "A crabeater seal (Lobodon carcinophagus) swimming around an iceberg in the waters off Troval Island, near Rothera Research Station.",
            "keywords": [
                "crabeater seal Troval Island"
            ],
            "orientation": "Landscape",
            "copyright": "Copyright held by photographer",
            "photographer": {
                "id": 605,
                "website": null,
                "name_last": "Souster",
                "name_first": "Terri",
                "organisation_name": null
            },
            "display_sizes": [
                {
                    "name": "small",
                    "watermarked": false,
                    "width": 218,
                    "height": 123,
                    "mime_type": "image/jpeg",
                    "href": "http://www.photo.antarctica.ac.uk/external/guest/photo/small/53616c7465645f5f1ed07d5a6f9084bc9a33e50b89550b1e2879820901a09503.jpg"
                },
                {
                    "name": "medium",
                    "watermarked": false,
                    "width": 350,
                    "height": 197,
                    "mime_type": "image/jpeg",
                    "href": "http://www.photo.antarctica.ac.uk/external/guest/photo/medium/53616c7465645f5f66ea5e1471e3efc4f304bad58bd3a2c1e5f2a54870e39042.jpg"
                },
                {
                    "name": "large",
                    "watermarked": true,
                    "width": 540,
                    "height": 304,
                    "mime_type": "image/jpeg",
                    "href": "http://www.photo.antarctica.ac.uk/external/guest/photo/large/53616c7465645f5fd2137f1000ae91291d56f990b31b57755c909c8e68064b1c.jpg"
                },
                {
                "name": "extra-large",
                    "watermarked": false,
                    "width": 1280,
                    "height": 721,
                    "mime_type": "image\/jpeg",
                    "href": "http:\/\/www.photo.antarctica.ac.uk\/external\/guest\/photo\/extra-large\/53616c7465645f5fe6c8c9728b16785106bf6cbaeeef802f636825e74213639e.jpg"
                }
            ],
            "categories": [
                {
                    "id": 55,
                    "parent_id": 80,
                    "name": "Crabeater"
                },
                {
                    "id": 80,
                    "parent_id": 113,
                    "name": "Seal"
                },
                {
                    "id": 113,
                    "parent_id": 0,
                    "name": "Wildlife"
                }
            ],
            "links": [
                {
                    "type": "website",
                    "action": "view",
                    "slug": "bas_image_collection",
                    "label": "BAS Image Collection",
                    "href": "http://www.photo.antarctica.ac.uk/external/guest/detail/search/10010516"
                },
                {
                    "type": "website",
                    "action": "purchase",
                    "slug": "bas_image_collection",
                    "label": "BAS Image Collection",
                    "href": "http://www.photo.antarctica.ac.uk/external/guest/detail/search/10010516"
                }
            ],
            "credit_line": "Terri Souster (British Antarctic Survey)",
            "contact_for_image": false,
            "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": [
                    "BAS Public website only"
                ]
            },
            "max_width": 3648,
            "max_height": 2056,
            "location_freeform": {
                "description": "Rothera Research Station, Adelaide Island",
                "latitude": "",
                "longitude": ""
            }
        }
    ],
    "meta": {
        "count": 47,
        "limit": 200
    }
}

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.