Overview

This project provides a simple REST API giving access to information about arts and humanities infrastructures in the United Kingdom.

Connecting to the API

Access the Mapping the Humanities API from this endpoint: https://www.humanities.org.uk

Authentication

No user authentication is required to access the API resources. Please be responsible.

HTTP response codes

200 OK

The API query was successful and has returned some data.

404 Not Found

You have hit an incorrect URL, or a record that no longer exists.

429 Rate Limit Exceeded

You have exceeded the allowed number of API requests. Please limit successive requests in order to not overwhelm our API.

500 Internal Server Error

The server hit an error whilst processing your requests. This is most likely a temporary issue which should resolve soon, however if you continue to experience issues please reach out to us.

Infrastructures

Infrastructure records can be listed out using this endpoint: https://www.humanities.org.uk/infrastructures

Code examples

PHP (Guzzle)

    
    use GuzzleHttp\Client;

    $client = new GuzzleHttp\Client([
        'base_uri' => 'https://www.humanities.org.uk/'
    ]);

    $response = $client->request('GET', 'infrastructures');
    

Python

    
    import requests

    response = requests.get("https://www.humanities.org.uk/infrastructures")
    

Response example:

    
    {
        "infrastructure_id": 123,
        "name": "Example Record",
        "description": "An example description for this record.",
        "addr1": "123 Street",
        "addr2": null,
        "town": "Cambridge",
        "county": Cambridgeshire,
        "postcode": "123456",
        "country": "United Kingdom",
        "tags": [
            "performing-processes",
            "artistic-research",
            "art-and-visual-culture"
        ],
        "ahrc_categories": [
            "visual-arts-design-history-theory-and-practice"
        ],
        "links": {
            "self": "/api/v1/infrastructures/123",
            "host_organisations": [
                {
                "organisation_id": 123,
                "name": "Associated University",
                "url": "/api/v1/organisations/123"
                }
            ],
            "child_infrastructures": [],
            "partners": []
        }
    },
    

Filtering

Use GET parameters

You can filter your results using GET parameters in the URL. For example:

• Search: https://www.humanities.org.uk/infrastructures?name=searchquery
• Postcode: https://www.humanities.org.uk/infrastructures?postcode=CB
• Tags: https://www.humanities.org.uk/infrastructures?tag=name-of-tag

Combine filters

Filters can also be combined. For example: https://www.humanities.org.uk/infrastructures?name=searchquery&postcode=CB

Pagination

Results are paginated. Details of the current pagination are in the “metadata” index, such as number of results and total pages.

Example:

    
    "metadata": {
        "num_results": 2392,
        "per_page": 15,
        "total_pages": 160,
        "next_page": "/api/v1/infrastructures?page=2"
    },
    

Specific infrastructure

You can query the details for a specific record if you know the ID, using this endpoint: https://www.humanities.org.uk/infrastructures/{infrastructure-id}

Organisations

Host organisations can also be queried in the same way as infrastructure records. The same filtering and pagination processes to this endpoint: https://www.humanities.org.uk/organisations.

Example:

    
    {
        "organisation_id": 123,
        "name": "Example University",
        "description": null,
        "addr1": "123 Street",
        "addr2": "",
        "town": "Cambridge",
        "county": Cambridgeshire,
        "postcode": "123456",
        "country": "United Kingdom",
        "links": {
            "self": "/api/v1/organisations/123",
            "child_infrastructures": [
                {
                    "infrastructure_id": 123,
                    "name": "Example child infrastructure name",
                    "url": "/api/v1/infrastructures/123"
                },
                {
                    "infrastructure_id": 456,
                    "name": "Another example",
                    "url": "/api/v1/infrastructures/456"
                }
            ]
        }
    },
    

Specific organisation

You can query the details for a specific organisation, if you know the ID. Use this endpoint: https://www.humanities.org.uk/organisations/{organisation-id}

AHRC categories

You can query AHRC categories to find how many records are tagged against them directly or indirectly. Use this endpoint: https://www.humanities.org.uk/categories

Example:

    
    "data": [
        {
            "category_id": 53,
            "parent_id": null,
            "colour": null,
            "direct_associations": 96,
            "related_associations": 6,
            "name": "Archaeology",
            "slug": "archaeology",
            "link" : "/api/v1/infrastructures?category=archaeology"
        },
        {
            "category_id": 74,
            "parent_id": 53,
            "colour": null,
            "direct_associations": 2,
            "related_associations": 96,
            "name": "Archaeology: Archaeology of Human Origins",
            "slug": "archaeology-archaeology-of-human-origins",
            "link" : "/api/v1/infrastructures?category=archaeology-archaeology-of-human-origins"
        },
        {
            "category_id": 93,
            "parent_id": 53,
            "colour": null,
            "direct_associations": 2,
            "related_associations": 96,
            "name": "Archaeology: Archaeology of Literate Societies",
            "slug": "archaeology-archaeology-of-literate-societies",
            "link" : "/api/v1/infrastructures?category=archaeology-archaeology-of-literate-societies"
        }
    ]