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

• Rijks
  • Gettting started
  • Installation
  • Usage
  • Rijks class
    • Constructor
    • Methods
      • getCollection
        • CollectionRequest
        • CollectionResponse
      • getCollectionDetails
        • CollectionDetailsRequst
        • CollectionDetailsResponse
      • getCollectionImage
        • CollectionImageRequest
        • CollectionImageResponse
  • Interfaces
    • Result
  • Types
    • ArtObject
    • ArtObjectDetails
    • ArtObjectPage
    • Color
    • CountFacets
    • Culture
    • Facet
    • FacetValue
    • Format
    • Image
    • Lavel
    • Link
    • Override
    • Rsponse
    • Sort
    • Tile
  • Authors
  • Links

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 interface 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 interface 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 interface handles all possible getCollectionDetails parameters.

interface CollectionDetailsRequest {
  objectNumber: string;
  format?: Format;
}

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

CollectionDetailsResponse

This interface handles getCollectionDetails response.

interface 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 interface handles all possible getCollectionImage parameters.

interface CollectionImageRequest {
  objectNumber: string;
}

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

CollectionImageResponse

This interface handles getCollectionImage response.

interface CollectionImageResponse {
  levels: Level[];
}

Interfaces

The following interfaces are used for mapping all API requests and responses. In case of complex structure, interfece are used in order to extends basic features.

Result

This interface handles all REST APIs responses.

interface Result<T extends Respnse> {
  success: boolean;
  status: number;
  data?: T;
  error?: string;
}

Types

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

ArtObject

This interface has the following structure:

interface 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 interface extends ArtObject with the following addon fields:

interface ArtObjectDetails extends ArtObject {
  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[];
}

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