Description

The method institutions returns a list of institutions which are registered at the DDB. This method provides response data only as application/json. It is a read-only service and must be accessed with a HTTP-GET-request.
GET /institutions?<QueryParameters> HTTP/1.1

Request Header

NameValue(s)RequiredRepeatableDefault valueDescription
Acceptapplication/json
*/*
yesnoapplication/jsonSpecifies the format of the accepted data. Every request needs to be sent with a valid Accept Header defining the requested response format. Otherwise the response to the request will be a 406 - Not acceptable status code. If the request accepts every kind of data (Accept: */*) JSON will be returned.
AuthorizationOAuth oauth_consumer_key="<API key>"yesnoAn API key is mandatory for data access. You may enclose it by either sending it as Query Parameter or (as mentioned here) in the Request Header.
Hostapi.deutsche-digitale-bibliothek.deyesnoThe host is mandatory.

Back To Top

Parameters

Query

ParameterValue(s)RequiredRepeatableDefault valueDescription
oauth_consumer_key<API key>yesnoAn API key is mandatory for data access. You may enclose it by either sending it as Query Parameter or (as mentioned here) in the Request Header.
sector<sector element>noyesThe sector the institutions should belong to. If more than one sector should be retrieved this parameter can be repeated (see sectors)

Back To Top

Authorization

This method needs an API key for authentication (Who are you?) and authorization (What you are authorized to do?). For more information please read the Authorization How-To.

This method is offered over HTTP and HTTP Secure.

Back To Top

Errors

CodeTextDescription
404Not FoundEither the item does not exist or has no data.
406Not AcceptableThe Request Header is not acceptable. Please see section Request Header.
500Server ErrorSomething went terribly wrong. An error message will provide a meaningful description.

Back To Top

Samples

Request 1

Request all institutions using authentication via Query Parameters.

GET /institutions?oauth_consumer_key=abcdefgh12345678 HTTP/1.1
Host: api.deutsche-digitale-bibliothek.de
Accept: application/xml

Response

[
    {
        "name": "Abenteuermuseum Saarbrücken",
        "id": "2GJUO7RSKB56546VZZIK5GN7GZUYU5L3",
        "latitude": "49.2401572",
        "longitude": "6.9969327",
        "sector": "sec_06"
    },
    {
        "name": "Adveniat-Bibliothek",
        "id": "S4RC3GUO3BPGUHLYYYXIFKL2CHQQKD2W",
        "latitude": "51.45427",
        "longitude": "7.01546",
        "sector": "sec_02"
    },
    {
        "name": "Akademie der Wissenschaften in Hamburg",
        "id": "L4CPXD3O2CRKVWVZ5ZCWTIAOA4UT3TPE",
        "latitude": "53.562655",
        "longitude": "9.987817",
        "sector": "sec_04"
    },
    {
        "name": "Alemannisches Institut Freiburg im Breisgau e.V.",
        "id": "WEVZTYMZKPRKULXN22O4BGBS3N3D3ZOR",
        "children":
        [
            {
                "name": "Alemannisches Institut, Arbeitsgruppe Tübingen",
                "id": "MXKPZWYNEUUZCDLAU4U5LCJJSUE2CUAH",
                "latitude": "48.5260861",
                "longitude": "9.0619226",
                "sector": "sec_04"
            }
        ],
        "latitude": "47.995737",
        "longitude": "7.8447692",
        "sector": "sec_04"
    },
    {
        "name": "Alpines Museum des DAV",
        "id": "5TUIDBWGTQL4C2V6USI4L3HLLBHF7KXY",
        "latitude": "48.1352079",
        "longitude": "11.5889841",
        "sector": "sec_06"
    },
    ...
]

 

Request 2

Request only museums (sec_06) user Authentication via HTTP Request Header.

GET /institutions?sector=sec_06 HTTP/1.1
Host: api.deutsche-digitale-bibliothek.de
Accept: */*
Authorization: OAuth oauth_consumer_key="abcdefgh12345678"

Response

[
    {
        "name": "Abenteuermuseum Saarbrücken",
        "id": "2GJUO7RSKB56546VZZIK5GN7GZUYU5L3",
        "latitude": "49.2401572",
        "longitude": "6.9969327",
        "sector": "sec_06"
    },
    {
        "name": "Alpines Museum des DAV",
        "id": "5TUIDBWGTQL4C2V6USI4L3HLLBHF7KXY",
        "latitude": "48.1352079",
        "longitude": "11.5889841",
        "sector": "sec_06"
    },
    {
        "name": "Alt-Arnstorf-Haus",
        "id": "JQADKD72P4O67OG7KERDZB4OQY4P5FRP",
        "children":
        [
            {
                "name": "Gollwitzer-Photoglasplattensammlung",
                "id": "UP63QLFLIUQHB2KXMOHBLHGVXBBLICRZ",
                "latitude": "48.56073",
                "longitude": "12.81708",
                "sector": "sec_01"
            }
        ],
        "latitude": "48.5601145",
        "longitude": "12.8193494",
        "sector": "sec_06"
    },
    ...
]

Back To Top