Introduction - ImpactU

The ImpactU API is a REST API that returns scientific and academic information in JSON: persons, products, affiliations, sources, patents, projects and geographic entities. Querying is public and read-only. With a session, the API also lets you manage users and upload institutions’ files.

Base URL

https://api.dev.impactu.colav.co

Every path in this documentation is appended to that URL. For example, GET /search/works is requested at https://api.dev.impactu.colav.co/search/works.

Response format

Responses are JSON and take two shapes, depending on the type of endpoint.

A resource
A list

Endpoints that return a single entity wrap the result in data and add meta, with the same shape as in lists (count is 1).

{
  "data": { "...": "..." },
  "meta": {
    "count": 1,
    "page": 1,
    "size": 1,
    "db_response_time_ms": 25,
    "cursor": { "next": null, "previous": null }
  }
}

Search endpoints return a list in data and the pagination data in meta.

{
  "data": [ { "...": "..." } ],
  "meta": {
    "count": 1542618,
    "page": 1,
    "size": 10,
    "db_response_time_ms": 348,
    "cursor": { "next": "https://...", "previous": null }
  }
}

Some endpoints return the object without the data wrapper: the available filters, the related affiliations (of an affiliation or of a geographic entity), /info and /info/quality. Exports return a CSV or Excel file.

The `meta` field of lists

object

Response metadata.

Show properties

integer

Total number of results matching the query.

integer

Current page.

integer

Number of results returned on this page.

integer

Database response time in milliseconds.

object

Show properties

string | null

URL of the next page.

string | null

URL of the previous page.

List conventions

The search endpoints share these query parameters.

string

Search text. Used by search-box queries.

integer

default:"10"

Results per page, from 1 to 250.

integer

default:"1"

Page number.

string

default:"citations_desc"

Sort with the format field_direction, where the direction is asc or desc. The valid fields depend on the entity and are described in each endpoint.

string

default:"full"

Level of detail of the response: full (every field) or summary (only the main fields). Accepted by lists and entity details, except the search and detail of geographic entities and news.

In addition, each list has its own filters. All of them accept several values separated by commas (for example, years=2020,2026), and the valid options can be looked up in each entity’s available-filters endpoint.

If you don’t send max, page or sort, max=10, page=1 and sort=citations_desc apply. If you send max and page without sort, sort=citations_desc applies.

Data and formats

Dates

Dates are given in Unix seconds. In end dates, a value of -1 means the relationship is still current.

Identifiers

Each entity has its own identifier format:

Entity	Example
Institution	`03bp5hc83` (ROR identifier)
Faculty	`03bp5hc83_20`
Department	`03bp5hc83_2_21620003_3154`
Research group	`COL0001262`
Person	`0000000001`
Product, source	`6ab555045418a51e325f5303`

Information by source

Many fields (names, citations, types, rankings) return one item per information source, with the fields source and provenance.

Authentication and limits

The query endpoints are public: they need no authentication and, for now, have no request limit. A session is required for user administration (/admin/users), API key management (/users/{email}/apikey), the session status (/me) and every file upload (/submit/staff, /submit/ciarp, /submit/scienti and /submit/project). The session is the JWT that Log in stores in the HttpOnly cookie access_token_cookie.

CSRF token. Session requests other than GET (POST, PUT, PATCH and DELETE) must send the X-CSRF-TOKEN header with the value of the csrf_access_token cookie, which logging in also creates. Without that header they return 401.
Deactivated accounts. Every session request checks that the account is still active. If an administrator deactivates it, or the account no longer exists, the token stops working at once and the request returns 403, even if the token has not expired.

Errors

When a request fails, the API responds with the HTTP code for the case and a message in error:

Code	When
`400`	A parameter is invalid: for example `max=0`, a badly formed `sort`, a `fields` field that is not allowed or a JSON body that is not an object.
`401`	The session is missing, the token is not valid or the `X-CSRF-TOKEN` header is missing.
`403`	The session has no permission for the operation or the account is deactivated.
`404`	The entity does not exist.
`409`	The operation clashes with an existing record, for example when creating a user.
`413`	The file exceeds the maximum size. Only in Validate projects file, with a maximum of 10 MB.
`415`	The file type is not allowed. Only in Send SCIENTI file.
`422`	The Staff or CIARP Excel file is missing columns or has unnamed columns.
`500`	Unexpected server error.
`502`	The email with the credentials could not be sent when creating a user, changing their email or resetting their password. No change is saved, so it can be retried.

{ "error": "The person with id 9999999999 does not exist." }

The authentication, user and file-upload endpoints respond with { "success": false, "msg": "..." } instead of error. Validate projects file uses error for file problems (400 and 413) and msg for session problems (401 and 403). Lists of an entity that does not exist (for example, the products of a nonexistent author) return 200 with an empty list.

The API’s own messages (the values of error and msg) are in Spanish. The response examples show them as the API returns them.

Available endpoints

Search

Search for persons, products, affiliations, sources, patents, projects and geography, with their available-filters endpoints.

Affiliation

An affiliation (institution, faculty, department or group), its related affiliations and its products, with filters, export and 30 indicators, patents, projects and news.

Person

An author’s profile and their products, with filters, export and 16 indicators, patents, projects and news.

Source

A source (journal, conference or other publication) and its products, with filters, export and 1 indicator.

Work

A bibliographic product by its identifier or by DOI, and the full list of its authors.

Patent

A patent and its authors.

Project

A research project and its authors.

Geo

A department or a city, with its affiliations and its products.

APC

CSV export of the APC data of a search, an author or an affiliation.

Completer

Autocomplete suggestions for authors, affiliations and sources.

Authentication

Logging in and out, and the session status.

Users

User administration, with the admin role, and management of your own API key.

Submit

Upload and validation of institutions’ files: Staff, CIARP, SCIENTI and projects.

System

General counts, data-quality metrics and ping.

​Base URL

​Response format

​The meta field of lists

​List conventions

​Data and formats

​Authentication and limits

​Errors

​Available endpoints

Search

Affiliation

Person

Source

Work

Patent

Project

Geo

APC

Completer

Authentication

Users

Submit

System

Base URL

Response format

The `meta` field of lists

List conventions

Data and formats

Authentication and limits

Errors

Available endpoints