Rijks

This package is a TypeScript based wrapper around the public REST APIs of Rijksmuseum (Amsterdam).

Prerequisites

In order to use this package, you need an api key: You can read more on how to obtain the API key on this page.

This package requires NodeJS (version 18 or later) and a node package manager (Npm, Yarn, Pnpm or Bun).

To make sure you have them available on your machine, try running the following command.

$ npm -v && node -v
v10.1.0
v18.18.0

Gettting started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Installation

BEFORE YOU INSTALL: please read the prerequisites.

Start with cloning this repo on your local machine:

$ git clone https://github.com/mariolazzari/rijks.git
$ cd rijks

To install and set up the library, run:

npm install @mariolazzari/rijks

Usage

Import package

import { Rijks } from "@mariolazzari/rijks"

Watch mode

npm test

Unit testing

npm test

Bulding new version

npm build

This task will create a distribution version of the project inside your local dist/ folder

Rijks class

Rijks class content handles all the requests and the responses to the three main Rijks museum REST APIs.

Constructor

In order to initialize Rijks client:

const rijks = new Rijks(API_KEY, culture?)

Constructor parameters

| Parameter | Type | Required | Default | | --------- | ------- | :------: | ------- | | apiKey | string | Yes | | | culture | Culture | No | en |

Methods

Rijks client includes the following three methods:

getCollection

Description

This asynchronous method handles GET /api/[culture]/collection REST API.

Prototype

async getCollection(params: CollectionRequest): Promise<Result<CollectionResponse>> 

Sample code

const params: CollectionRequest = {searchTerm: "Vermeer"}
const collection: CollectionResponse = await rijks.getCollection(params)

CollectionRequest

This type contains all the possible parameters handled by getCollection method.

| Parameter | Type | Required | Default | | ------------- | ------- | :------: | ------- | | searchTerm | string | Yes | | | page | number | Yes | 1 | | perPage | number | Yes | 10 | | format | Format | | json | | culture | Culture | | en | | involvedMaker | string | | | | type | string | | | | material | string | | | | technique | string | | | | period | string | | | | hex | string | | | | imageOnly | string | | true | | topPieces | string | | true | | sort | Sort | | |

CollectionResponse

This type contains all the values returned by getCollection method

| Value | Type | Required | Default | | ------------------- | ------------ | :------: | :-----: | | elapsedMilliseconds | number | Yes | 0 | | count | number | Yes | 0 | | countFacets | CountFacets | | [] | | artObjects | ArtObjects[] | | [] | | facets | Facet[] | | [] |

getCollectionDetails

Description

This method handles GET /api/[culture]/collection/[object-number] REST API.

Prototype

async getCollectionDetails(params:CollectionDetailsRequst) : Promise<Result<CollectionDetailsResponse>>

CollectionDetailsRequst

This type handles all possible getCollectionDetails parameters.

type CollectionDetailsRequest = {
  objectNumber: string;
  format?: Format;
}

| Parameter | Type | Required | Default | | ------------ | ------ | :------: | ------- | | objectNumber | string | Yes | | | format | Format | | json |

CollectionDetailsResponse

This type handles getCollectionDetails response.

type CollectionDetailsResponse = {
  elapsedMilliseconds: number;
  artObject: ArtObjectDetails;
  artObjectPage: ArtObjectPage;
}

getCollectionImage

Description

This method handles GET /api/[culture]/collection/[object-number]/tiles REST API.

Prototype

async getCollectionImage(params:CollectionImageRequst) : Promise<Result<CollectionImageResponse>>

CollectionImageRequest

This type handles all possible getCollectionImage parameters.

type CollectionImageRequest = {
  objectNumber: string;
}

| Parameter | Type | Required | Default | | ------------ | ------ | :------: | ------- | | objectNumber | string | Yes | |

CollectionImageResponse

This type handles getCollectionImage response.

type CollectionImageResponse = {
  levels: Level[];
}

Types

In order to implement all features, the following common types have been implemended:

Result

This type is a discriminated union that handles all REST APIs responses.

export type Result<T extends Response> =
  | {
      success: true;
      data: T;
    }
  | {
      success: false;
      error: string;
    };

ArtObject

This type has the following structure:

type ArtObject = {
  links: Link;
  id: string;
  objectNumber: string;
  title: string;
  hasImage: boolean;
  principalOrFirstMaker: string;
  longTitle: string;
  showImage: boolean;
  permitDownload: boolean;
  webImage?: Image;
  headerImage?: Image;
  productionPlaces: string[];
};

ArtObjectDetails

This type extends ArtObject with the following addon fields:

export type ArtObjectDetails = {
  priref: string;
  language: Culture;
  copyrightHolder?: string;
  colors: Color[];
  colorsWithNormalization: ColorNormalization[];
  normalizedColors: Color[];
  normalized32Colors: Color[];
  materialsThesaurus: string[];
  techniquesThesaurus: string[];
  productionPlacesThesaurus: string[];
  titles: string[];
  description: string;
  labelText?: string;
  objectTypes: string[];
  objectCollection: string[];
  makers: string[];
} & ArtObject;

ArtObjectPage

This type handles ArtObjectPage properties.

type ArtObjectPage = {
   id: string;
  similarPages: string[];
  lang: Culture;
  objectNumber: string;
  tags: string[];
  plaqueDescription: string;
  audioFile1?: string;
  audioFileLabel1?: string;
  audioFileLabel2?: string;
  createdOn: string;
  updatedOn: string;
  adlibOverrides: Override;
};

Color

This type handles ArtObjectDetails color properties.

type Color = {
  percentage: number;
  hex: string;
};

CountFacets

This type has the following definition:

type CountFacets = {
  hasimage: number;
  ondisplay: number;
};

Culture

This type contains all supported cultures.

type Culture = "en | nl"

Facet

This type contains facet properties.

type Facet = {
  facets: FacetValue[];
  name: string;
  otherTerms: number;
  prettyName: number;
};

FacetValue

This type contains facet key / value pairs for Facet type.

type FacetValue = {
  key: string;
  value: number;
};

Format

This type contains all supported APU repsonse types.

type Format = "json" | "jsonp" | "xml";

Image

This type contains all images properties.

type Image = {
  guid: string;
  offsetPercentageX: number;
  offsetPercentageY: number;
  width: number;
  height: number;
  url: string;
};

Lavel

This type contains level properties.

type Level = {
  name: string;
  width: number;
  height: number;
  tiles: Tile[];
};

Link

This type contains link properties.

type Link = {
  self?: string;
  web?: string;
  search?: string;
};

Override

This type handles optional overrides in ArtObjectPage type.

type Override = {
  titel?: string;
  maker?: string;
  etiketText?: string;
};

Rsponse

This union type contains all possible API repsonse types.

export type Response =
  | CollectionResponse
  | CollectionDetailsResponse
  | CollectionImageResponse;

Sort

Sort type contains all supported sorting criterias.

type Sort = | "relevance" 
  | "objectYype" 
  | "chronologic" 
  | "achronologic" 
  | "artist" 
  | "artistDesc"

Tile

This type contains all tile properties.

type Tile = {
  x: number;
  y: number;
  url: string;
};

Authors

• Mario Lazzari - Initial work

Links

• Demo app
• My personal site
• My github profile
• Rijksmuseum API documentation