Locations API Documentation - Version 1

Resources - Gazetteer (Gazetteers)

Gazetteers represent meta-data and references to sources of place-names in Antarctica, the Arctic and South Georgia.

Resource model

Name Property Name Data Type Optional Description
Id id Integer No Unique identifer for this gazetteer
Gazetteer gazetteer String No Code name of this gazetteer
Title title String No Human-friendly name of this gazetteer
Attribution attribution String No Data provider name
Website website String No Data provider website URL
Composite composite Boolean No True if this is a multi-lingual gazetteer with place-names assigned by multiple nations
Trigger length triggerlength Integer No Number of significant characters required in search strings before data is returned [1]

[1] This feature restricts the amount of information potentially returned (gazetteers are large). It is not intended that the locations API be used e.g. to find all CGA place-names starting with the letter ‘R’.

This table lists the possible values gazetteer can be.

gazetteer property value Data provider
bat Antarctic Place-names Committee (APC)
cga Composite Gazetteer of Antarctica (CGA)
sgssi Gazetteer of South Georgia Place-names
arctic Gazetteer of Arctic Place-names

Example (JSON)

{
    "data": {
        "id": 1,
        "gazetteer": "bat",
        "title": "APC gazetteer",
        "attribution": "UK Antarctic Place-names Committee (APC)",
        "website": "http://apc.antarctica.ac.uk",
        "composite": false,
        "triggerlength": 4
    }
}

Resource methods

GET/gazetteer

Returns a 200 OK status and metadata for all currently supported gazetteers.

Parameters

None.

Options

None.

Example request

URL: https://api.bas.ac.uk/locations/v1/gazetteer

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": 1,
            "gazetteer": "bat",
            "title": "APC gazetteer",
            "attribution": "UK Antarctic Place-names Committee (APC)",
            "website": "http://apc.antarctica.ac.uk",
            "composite": false,
            "triggerlength": 4
        },
        {
            "id": 2,
            "gazetteer": "cga",
            "title": "Composite Gazetteer of Antarctica (CGA)",
            "attribution": "Secretariat SCAR (1992, updated 2015). Composite Gazetteer of Antarctica, Scientific Committee on Antarctic Research",
            "website": "http://gcmd.nasa.gov/records/SCAR_Gazetteer.html",
            "composite": true,
            "triggerlength": 4
        }
    ]
}

GET/gazetteer/{source}

Returns a 200 OK status and metadata for the gazetteer with code-name source.

Parameters
Name Field Name Data Type Required Valid Value(s) Description
source {source} String Yes bat|cga Code name for desired gazetteer
Options

None.

Example request

URL: https://api.bas.ac.uk/locations/v1/gazetteer/cga

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": 2,
        "gazetteer": "cga",
        "title": "Composite Gazetteer of Antarctica (CGA)",
        "attribution": "Secretariat SCAR (1992, updated 2015). Composite Gazetteer of Antarctica, Scientific Committee on Antarctic Research",
        "website": "http://gcmd.nasa.gov/records/SCAR_Gazetteer.html",
        "composite": true,
        "triggerlength": 4
    }
}
Example request

URL: https://api.bas.ac.uk/locations/v1/gazetteer/does-not-exist

Example response (404 Not Found)
Headers
Key Value
Content-Type application/json
Body (JSON)
{
    "status": 404,
    "detail": "Gazetteer does-not-exist is unknown"
}

GET/gazetteer/{source}/{q}/{level}

Returns the place-names from the gazetteer with code-name source whose name field starts with the search term q. Optionally return a field set according to level.

Parameters
Name Field Name Data Type Required Valid Value(s) Description
source {source} String Yes bat|cga Code name for desired gazetteer
q {q} String Yes   Search query [1] [2] [3]
level {level} String No brief|full field set level [4]

[1] Note that searching will only be triggered once the search term contains the minimum number of characters as defined in the triggerlength property for the parent gazetteer. [2] Fuzzy string matching will be used to determine hits, so e.g. it is possible to enter non-accented characters and return accented results. [3] Note that the default fields returned for a location will depend on the gazetteer source requested - see the example requests for the default set in each case. [4] See example responses for fields returned for brief and full - default is brief.

Options

None.

Example request

URL: https://api.bas.ac.uk/locations/v1/gazetteer/bat/rothera

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": 3608,
            "cga_id": 12397,
            "placename": "Rothera",
            "lat": -67.5696,
            "lon": -68.1252,
            "parent": "Rothera Point",
            "londms": "68°07\u002730.7\"W",
            "latdms": "67°34\u002710.6\"S"
        },
        {
            "id": 3609,
            "cga_id": 12396,
            "placename": "Rothera Point",
            "lat": -67.5693,
            "lon": -68.127,
            "parent": "Place Holder -17761",
            "londms": "68°07\u002737.2\"W",
            "latdms": "67°34\u00279.5\"S"
        }
    ]
}
Example request

URL: https://api.bas.ac.uk/locations/v1/gazetteer/bat/anvers/full

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": 126,
            "cga_id": 431,
            "placename": "Anvers Island",
            "description": "between 64°15' and 64°50'S, and 62°45' and 64°20'W, off Danco Coast ...",
            "level": 8,
            "parent": "Palmer Archipelago",
            "x": -2515155.1414,
            "y": 1241336.567,
            "lat": -64.5934,
            "lon": -63.7317,
            "londms":"63°43\u002754.1\"W",
            "latdms":"64°35\u002736.2\"S"
        }
    ]
}
Example request

URL: https://api.bas.ac.uk/locations/v1/gazetteer/cga/rothera/brief

Example response (200 OK)
Headers
Key Value
Content-Type application/json
Body (JSON)
{
    "data": [
        {
            "id": 110947,
            "scar_id": 12397,
            "placename": "Rothera",
            "gazetteer": "GBR",
            "lat": -67.5675,
            "lon": -68.1297,
            "londms":"68°07\u002746.9\"W",
            "latdms":"67°34\u00273.0\"S"
        },
        {
            "id": 120304,
            "scar_id": 12397,
            "placename": "Rothera /Brit./",
            "gazetteer": "RUS",
            "lat": -67.5667,
            "lon": -68.1167,
            "londms":"68°07\u0027.1\"W",
            "latdms":"67°34\u0027.1\"S"
        },
        {
            "id": 110948,
            "scar_id": 12396,
            "placename": "Rothera Point",
            "gazetteer": "GBR",
            "lat": -67.5675,
            "lon": -68.1297,
            "londms":"68°07\u002746.9\"W",
            "latdms":"67°34\u00273.0\"S"
        },
        {
            "id": 130971,
            "scar_id": 12396,
            "placename": "Rothera Point",
            "gazetteer": "USA",
            "lat": -67.5667,
            "lon": -68.1333,
            "londms":"68°07\u002759.9\"W",
            "latdms":"67°34\u0027.1\"S"
        },
        {
            "id": 102057,
            "scar_id": 12396,
            "placename": "Rothera, punta",
            "gazetteer": "ARG",
            "lat": -67.5667,
            "lon": -68.1333,
            "londms":"68°07\u002759.9\"W",
            "latdms":"67°34\u0027.1\"S"
        },
        {
            "id": 136303,
            "scar_id": 12397,
            "placename": "Rothera Station",
            "gazetteer": "USA",
            "lat": -67.5694,
            "lon": -68.12,
            "londms":"68°07\u002712.0\"W",
            "latdms":"67°34\u00279.8\"S"
        }
    ]
}
Example request

URL: https://api.bas.ac.uk/locations/v1/gazetteer/cga/anvers/full

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": 104889,
            "scar_id": 431,
            "placename": "Anvers, Ile",
            "lat": -64.55,
            "lon": -63.5833,
            "altitude": "",
            "feature_type_code": "223",
            "description": "Province et ville qui appuyerent financierement l'Expedition Antarctique Belge de la Belgica sous le commandement de A. de Gerlache.",
            "date_named": "",
            "gazetteer": "BEL",
            "display_scales": "",
            "x": -2516360.6893,
            "y": 1250044.7798,
            "londms":"63°34\u002759.9\"W",
            "latdms":"64°33\u002700\"S"
        },
        {
            "id": 105112,
            "scar_id": 431,
            "placename": "Anvers, Isla",
            "lat": -64.5667,
            "lon": -63.5,
            "altitude": "",
            "feature_type_code": "223",
            "description": "El nombre le fue puesto en 1898 por la Expedicion Antartica Belga al mando del teniente Adrien de Gerlache, en la nave 'Belgica'...",
            "date_named": "",
            "gazetteer": "CHL",
            "display_scales": "",
            "x": -2512839.9369,
            "y": 1252855.7765,
            "londms":"63°30\u002700\"W",
            "latdms":"64°34\u0027.1\"S"
        },
        {
            "id": 107538,
            "scar_id": 431,
            "placename": "Anvers Island",
            "lat": -64.5833,
            "lon": -63.5,
            "altitude": "",
            "feature_type_code": "223",
            "description": "between 64?15' and 64?50'S, and 62?45' and 64?20'W, off Danco Coast, was discovered by Biscoe who made a landing on Biscoe Bay (q.v.) on 21 February 1832...",
            "date_named": "Tue Sep 08 00:00:00 BST 1953",
            "gazetteer": "GBR",
            "display_scales": "",
            "x": -2511140.0789,
            "y": 1252008.2586,
            "londms":"63°30\u002700\"W",
            "latdms":"64°34\u002759.9\"S"
        },
        {
            "id": 116843,
            "scar_id": 431,
            "placename": "Anvers Island",
            "lat": -64.55,
            "lon": -63.5833,
            "altitude": "",
            "feature_type_code": "223",
            "description": "",
            "date_named": "",
            "gazetteer": "RUS",
            "display_scales": "",
            "x": -2516360.6893,
            "y": 1250044.7798,
            "londms":"63°34\u002759.9\"W",
            "latdms":"64°33\u002700\"S"
        },
        {
            "id": 121858,
            "scar_id": 431,
            "placename": "Anvers Island",
            "lat": -64.55,
            "lon": -63.5833,
            "altitude": "",
            "feature_type_code": "223",
            "description": "High, mountainous island 38 mi long, which is the largest feature in the Palmer Archipelago, lying SW of Brabant Island at the SW end of the group...",
            "date_named": "Wed Jan 01 00:00:00 GMT 1947",
            "gazetteer": "USA",
            "display_scales": "",
            "x": -2516360.6893,
            "y": 1250044.7798,
            "londms":"63°34\u002759.9\"W",
            "latdms":"64°33\u002700\"S"
        },
        {
            "id": 116844,
            "scar_id": 432,
            "placename": "Anvers Island (Base N) /Brit/",
            "lat": -64.75,
            "lon": -64.0833,
            "altitude": "",
            "feature_type_code": "",
            "description": "",
            "date_named": "",
            "gazetteer": "RUS",
            "display_scales": "",
            "x": -2506678.3918,
            "y": 1218078.8447,
            "londms":"64°04\u002759.9\"W",
            "latdms":"64°45\u002700\"S"
        }
    ]
}

GET/placename/{source}/{id}

Returns the full complement of place-name fields for name id in the gazetteer with code-name source.

Parameters
Name Field Name Data Type Required Valid Value(s) Description
source {source} String Yes bat|cga Code name for desired gazetteer
id {id} Integer Yes   id of place-name
Options

None.

Example request

URL: https://api.bas.ac.uk/locations/v1/placename/bat/458

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": 458,
        "cga_id": 1554,
        "placename": "Bombardier Glacier",
        "previousname": "",
        "description": " flowing SE from Detroit Plateau to join Edgeworth Glacier, Nordenskjöld Coast, was surveyed by FIDS from \"Hope Bay\", 1960-61;...",
        "level": 9,
        "parent": "Detroit Plateau",
        "x": -2455623.7491,
        "y": 1416172.5588,
        "lat": -64.331,
        "lon": -60.0277
    }
}
Example request

URL: https://api.bas.ac.uk/locations/v1/placename/bat/100000

Example response (404 Not Found)
Headers
Key Value
Content-Type application/json
Body (JSON)
{
    "status": 404,
    "detail": "Failed to find place-name with id 100000 in gazetteer bat"
}

GET/description/{source}/{id}

Returns the full description (potentially long and containing diacritics) for place-name id in the gazetteer with code-name source.

Traits
Trait Enabled
Authenticated No
Parameters
Name Field Name Data Type Required Valid Value(s) Description
source {source} String Yes bat|cga Code name for desired gazetteer
id {id} Integer Yes   id of place-name
Options

None.

Example request

URL: https://api.bas.ac.uk/locations/v1/description/bat/458

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": " flowing SE from Detroit Plateau to join Edgeworth Glacier, Nordenskjöld Coast, was surveyed by FIDS from \"Hope Bay\", 1960-61; ...",
}

GET/nearby/{source}/{lon}/{lat}/{r}

Returns all the place-names in gazetteer with code-name source which lie within r metres of point with (lon,lat).

Traits
Trait Enabled
Authenticated No
Parameters
Name Field Name Data Type Required Valid Value(s) Description
source {source} String Yes bat|cga Code name for desired gazetteer
lon {lon} Float Yes   longitude of point (-180.0 <= lon <= 180.0)
lat {lat} Float Yes   latitude of point (-90.0 <= lat <= 90.0)
r {r} Float No 1000 to 1000000 inclusive search radius in metres [1]

[1] Defaults to 1000.

Options

None.

Example request

URL: https://api.bas.ac.uk/locations/v1/nearby/bat/-68.1252/-67.5696/2000

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": 3608,
            "placename": "Rothera",
            "longitude": -68.1252,
            "latitude": -67.5696,
            "dist": 2.2
        },
        {
            "id": 3609,
            "placename": "Rothera Point",
            "longitude": -68.127,
            "latitude": -67.5693,
            "dist": 81.6
        },
        {
            "id": 3030,
            "placename": "North Cove",
            "longitude": -68.1227,
            "latitude": -67.5664,
            "dist": 376.5
        },
        {
            "id": 409,
            "placename": "Biscoe Wharf",
            "longitude": -68.1319,
            "latitude": -67.5729,
            "dist": 471.2
        },
        {
            "id": 3956,
            "placename": "South Cove",
            "longitude": -68.1362,
            "latitude": -67.5701,
            "dist": 479
        },
        {
            "id": 4772,
            "placename": "Exhibition Buttress",
            "longitude": -68.1454,
            "latitude": -67.5647,
            "dist": 1031.1
        },
        {
            "id": 4861,
            "placename": "Repeater Buttress",
            "longitude": -68.1526,
            "latitude": -67.559,
            "dist": 1679.8
        }
    ]
}
Example request

URL: https://api.bas.ac.uk/locations/v1/nearby/bat/-68.1252/-67.5696/2000000

Example response (400 Bad Request)
Headers
Key Value
Content-Type application/json
Body (JSON)
{
    "status": 400,
    "detail": "1000 < r < 1000000"
}

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.