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

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.

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

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 content handles all the requests and the responses to the three main Rijks museum REST APIs.

In order to initialize Rijks client:

const rijks = new Rijks(API_KEY, culture?)

Constructor parameters

Rijks client includes the following three methods:

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)

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

This interface contains all the values returned by getCollection method

Description

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

Prototype

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

This interface handles all possible getCollectionDetails parameters.

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

This interface handles getCollectionDetails response.

interface CollectionDetailsResponse {
  elapsedMilliseconds: number;
  artObject: ArtObjectDetails;
  artObjectPage: ArtObjectPage;
}

Description

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

Prototype

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

This interface handles all possible getCollectionImage parameters.

interface CollectionImageRequest {
  objectNumber: string;
}

This interface handles getCollectionImage response.

interface CollectionImageResponse {
  levels: Level[];
}

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.

This interface handles all REST APIs responses.

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

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

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[];
};

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[];
}

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;
};

This type handles ArtObjectDetails color properties.

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

This type has the following definition:

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

This type contains all supported cultures.

type Culture = "en | nl"

This type contains facet properties.

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

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

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

This type contains all supported APU repsonse types.

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

This type contains all images properties.

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

This type contains level properties.

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

This type contains link properties.

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

This type handles optional overrides in ArtObjectPage type.

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

This union type contains all possible API repsonse types.

export type Response =
  | CollectionResponse
  | CollectionDetailsResponse
  | CollectionImageResponse;

Sort type contains all supported sorting criterias.

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

This type contains all tile properties.

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

• Mario Lazzari - Initial work

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