@mariolazzari/rijks

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