Skip to content

Institution Resource

Introduction

The Institution Resource provides detailed information about institutions, such as universities or other educational and research organizations. This resource supports multi-language fields for key attributes, allowing for comprehensive and localized data representation.

Institution Object

The institution resource includes the following fields:

Field Type Description Possible values Default
_id Integer Unique identifier for the institution
_links Object Contains links to related resources, such as metrics
name Array (required) Multi-language representation of the institution's full name (s. Multi-language Representation Format)
name_short String Short name or abbreviation of the institution
description Array Multi-language representation of the institution's description
type String The category or classification of the institution. university, school, company, other university
street String Street address of the institution null
zip String Postal code of the institution null
city Array (required) Multi-language representation of the city where the institution is located
country String (required) Country code in ISO 3166-1 alpha-2 format DE
phone_number String Primary phone number of the institution null
url String URL of the institution null
realm Object Information about the associated realm

For metrics related to institutions, refer to the institution metrics resource.

Managing Institution Resources

GET: Getting an Institution

An institution resources can be fetched by it's ID using an HTTP GET request.

Endpoint

GET https://api.openpublishing.com/resource/v3/institutions/[ID]

Response Structure

The response is a JSON object with the institution object.

POST: Adding New Institutions

New institution resources can be added to the system using an HTTP POST request. The request must include all required fields for the institution resource in the body.

Endpoint

POST https://api.openpublishing.com/resource/v3/institutions

Request Body Example

{
   "city": [
      {
         "language": "ger",
         "text": "München"
      },
      {
         "language": "eng",
         "text": "Munich"
      }
   ],
   "country": "DE",
   "description": [
      {
         "language": "ger",
         "text": "Die Ludwig-Maximilians-Universität gehört zu den größten und forschungsstärksten Universitäten Europas. Mit ihrem ausdifferenzierten Fächerspektrum verfügt sie über ein herausragendes Potenzial für zukunftsweisende Forschung."
      },
      {
         "language": "eng",
         "text": "The LMU is one of the most prestigious and traditional universities in Europe. It combines outstanding research with a challenging range of courses."
      }
   ],
   "name": [
      {
         "language": "ger",
         "text": "Ludwig-Maximilians-Universität, München"
      },
      {
         "language": "eng",
         "text": "Ludwig-Maximilians-Universität Munich"
      }
   ],
   "name_short": "LMU München",
   "phone_number": "+49 (0) 89 / 2180 - 0",
   "realm": {
      "_id": 1
   },
   "street": "Geschwister-Scholl-Platz 1",
   "url": "https://www.lmu.de",
   "zip": "80539"
}

PUT: Modifying Existing Institutions

Existing institution resources can be updated using an HTTP PUT request. The request body should contain the updated fields for the resource.

Endpoint

PUT https://api.openpublishing.com/resource/v3/institutions/[ID]

Request Body Example

{
   "name": [
      {
         "language": "ger",
         "text": "Ludwig-Maximilians-Universität München"
      },
   ],
   "phone_number": "+49 (0) 89 / 2180 - 1000"
}

DEL: Deleting Institutions

Institution resources can be deleted using an HTTP DELETE request. This action permanently removes the resource.

Endpoint

DELETE https://api.openpublishing.com/resource/v3/institutions/[ID]

Resource Queries

Querying Institutions (GET)

Endpoint

GET https://api.openpublishing.com/resource/v3/institutions

The API supports various filter operations and pagination to query institution data efficiently. Refer to the resource queries documentation for additional details.

Response Structure

The response is a JSON object with the following structure:

Field Type Description
_links Object Contains links to related resources, such as metrics and the resource itself
items Array An array of individual institution objects

Each item in the items array represents a single institution.

Search Capabilities

The Institutions API supports powerful search capabilities to find specific resources based on institution names or perform full-text searches across multiple fields. These search parameters enable clients to retrieve relevant data efficiently.

Search Parameters

Parameter Description Notes
name Search for institutions by their name using search operators. s. resource queries sytax
name_short Search for institutions by their short name using search operators. s. resource queries sytax
q Perform a full-text search across multiple fields.

Examples

GET https://api.openpublishing.com/resource/v3/institutions?q=techni+berlin

returns

{
   "_links": {
      "first": "https://api.openpublishing.com/resource/v3/institutions?q=techni+berlin&page=1",
      "last": "https://api.openpublishing.com/resource/v3/institutions?q=techni+berlin&page=1",
      "next": null,
      "prev": null,
      "self": "https://api.openpublishing.com/resource/v3/institutions?q=techni+berlin"
   },
   "items": [
      {
         "_id": 5,
         "_links": {
            "metrics": "https://api.openpublishing.com/resource/v3/institutions/5/metrics",
            "self": "https://api.openpublishing.com/resource/v3/institutions/5"
         },
         "city": [
            {
               "language": "ger",
               "text": "Berlin"
            },
            {
               "language": "eng",
               "text": "Berlin"
            }
         ],
         "country": "DE",
         "description": [
            {
               "language": "ger",
               "text": null
            },
            {
               "language": "eng",
               "text": null
            }
         ],
         "name": [
            {
               "language": "ger",
               "text": "Technische Universität Berlin"
            },
            {
               "language": "eng",
               "text": "Technical University of Berlin"
            }
         ],
         "name_short": "TU Berlin",
         "phone_number": "+49 (0)30 314-0",
         "realm": {
            "_id": 1,
            "_links": {
               "self": "https://api.openpublishing.com/resource/v3/realms/3033"
            },
            "name": "goldenpage",
            "screenname": "Golden Page Press"
         },
         "street": "Straße des 17. Juni 135",
         "type": "university",
         "url": "https://www.tu.berlin/",
         "zip": "10623"
      },
      {
         "_id": 98,
         "_links": {
            "metrics": "https://api.openpublishing.com/resource/v3/institutions/98/metrics",
            "self": "https://api.openpublishing.com/resource/v3/institutions/98"
         },
         "city": [
            {
               "language": "ger",
               "text": "Berlin"
            },
            {
               "language": "eng",
               "text": "Berlin"
            }
         ],
         "country": "DE",
         "description": [
            {
               "language": "ger",
               "text": null
            },
            {
               "language": "eng",
               "text": null
            }
         ],
         "name": [
            {
               "language": "ger",
               "text": "Hochschule für Technik und Wirtschaft Berlin"
            },
            {
               "language": "eng",
               "text": "University of Applied Sciences Berlin"
            }
         ],
         "name_short": "HTW Berlin",
         "phone_number": "+49 30 5019-0",
         "realm": {
            "_id": 1,
            "_links": {
               "self": "https://api.openpublishing.com/resource/v3/realms/3033"
            },
            "name": "goldenpage",
            "screenname": "Golden Page Press"
         },
         "street": "Treskowallee 8",
        "type": "university",
        "url": "https://www.htw-berlin.de/",
        "zip": "10318"
      }
   ]
}

Example 2: Search Institutions by name or `name_short``

GET https://api.openpublishing.com/resource/v3/institutions?name_short=tu+berlin
GET https://api.openpublishing.com/resource/v3/institutions?name__startswith=Ludwig
GET https://api.openpublishing.com/resource/v3/institutions?name__contains=Maximilian

return corresponding lists of institutions matching the specified texts.