@mariolazzari/rijks

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

Rijks

---

This package is a 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 thrre 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

Result

This interface handles all REST APIs responses.

interface Result<T> {
  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[];
}

Color type

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 type

This type contains all supported cultures.

type Culture = "en | nl"

Facet type

This type contains facet properties.

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

FacetValue type

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

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

Format type

This type contains all supported APU repsonse types.

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

Image type

This type contains all images properties.

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

Lavel type

This type contains level properties.

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

Link type

This type contains link properties.

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

Sort type

Sort type contains all supported sorting criterias.

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

Tile type

This type contains all tile properties.

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

Methods

Rijks client includes the following three methonds:

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

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

Authors

• Mario Lazzari - Initial work

Links

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