A lightweight TypeScript client for the Metropolitan Museum of Art Collection API.
Install with Bun:
bun add @jwd-gg/metOr with npm/yarn:
npm install @jwd-gg/met --save
# or
yarn add @jwd-gg/metimport { fetcher } from '@jwd-gg/met';
async function main() {
try {
const { total, objectIDs } = await fetcher.getObjects();
console.log(`Found ${total} objects. First IDs:`, objectIDs.slice(0, 5));
const firstId = objectIDs[0];
const details = await fetcher.getObject(firstId);
console.log(`Title of object ${firstId}:`, details.title);
} catch (err) {
console.error(err);
}
}
main();
// Found 495651 objects. First IDs: [ 1, 2, 3, 4, 5 ]
// Title of object 1: One-dollar Liberty Head CoinFetches the total number of objects and a list of all object IDs currently in the collection that are available via the API.
Signature:
fetcher.getObjects(): Promise<ObjectsResponse>Returns: Promise<ObjectsResponse>
View ObjectsResponse Type
export interface ObjectsResponse {
/** The total number of object IDs */
total: number;
/** An array of object IDs */
objectIDs: number[];
}Retrieves detailed information for a single object identified by its objectID.
Signature:
fetcher.getObject(id: number): Promise<ObjectDetails>Parameters:
id(number): The unique identifier for the object.
Returns: Promise<ObjectDetails>
View ObjectDetails Type
// Note: Some fields are optional and may not be present for all objects.
interface Constituent {
constituentID: number;
role: string;
name: string;
constituentULAN_URL?: string;
constituentWikidata_URL?: string;
gender?: string;
}
interface ElementMeasurements {
Height?: number;
Width?: number;
Depth?: number;
Length?: number;
[key: string]: number | undefined;
}
interface Measurement {
elementName: string;
elementDescription: string | null;
elementMeasurements: ElementMeasurements;
}
interface ParsedDimension {
element: string;
dimensionType: string;
dimension: number;
}
interface Tag {
term: string;
AAT_URL: string;
Wikidata_URL?: string;
}
export interface ObjectDetails {
/** A unique identifier for the object */
objectID: number;
/** Indicates if the object is a highlight */
isHighlight: boolean;
/** The object's accession number */
accessionNumber: string;
/** The year the object was accessioned */
accessionYear: string;
/** Indicates if the object is in the public domain */
isPublicDomain: boolean;
/** URL to the primary image */
primaryImage: string;
/** URL to a smaller version of the primary image */
primaryImageSmall: string;
/** URLs to additional images, if available */
additionalImages: string[];
/** Information about the artists or makers */
constituents: Constituent[] | null;
/** The department associated with the object */
department: string;
/** The type of object */
objectName: string;
/** The title of the object */
title: string;
/** Information about the culture or people associated with the object */
culture: string;
/** The historical period */
period: string;
/** The dynasty, if applicable */
dynasty: string;
/** The reign, if applicable */
reign: string;
/** Portfolio information, if applicable */
portfolio: string;
/** Role of the primary artist */
artistRole: string;
/** Prefix for the artist's name */
artistPrefix: string;
/** Display name for the artist */
artistDisplayName: string;
/** Biographical information for the artist */
artistDisplayBio: string;
/** Suffix for the artist's name */
artistSuffix: string;
/** Sorted version of the artist's name */
artistAlphaSort: string;
/** Nationality of the artist */
artistNationality: string;
/** Start year of the artist's life */
artistBeginDate: string;
/** End year of the artist's life */
artistEndDate: string;
/** Gender of the artist */
artistGender?: string;
/** Wikidata URL for the artist */
artistWikidata_URL?: string;
/** ULAN URL for the artist */
artistULAN_URL?: string;
/** Date of the object's creation or origin */
objectDate: string;
/** Start year for the object's date */
objectBeginDate: number;
/** End year for the object's date */
objectEndDate: number;
/** Materials used to create the object */
medium: string;
/** Text description of the object's dimensions */
dimensions: string;
/** Parsed dimensions, if available */
dimensionsParsed: ParsedDimension[] | null;
/** Detailed measurements, if available */
measurements: Measurement[] | null;
/** Credit line for the object */
creditLine: string;
/** Type of geographical location associated with the object */
geographyType: string;
/** City associated with the object */
city: string;
/** State associated with the object */
state: string;
/** County associated with the object */
county: string;
/** Country associated with the object */
country: string;
/** Region associated with the object */
region: string;
/** Subregion associated with the object */
subregion: string;
/** Locale associated with the object */
locale: string;
/** Locus associated with the object */
locus: string;
/** Excavation site, if applicable */
excavation: string;
/** River associated with the object */
river: string;
/** General classification of the object */
classification: string;
/** Rights and reproduction information */
rightsAndReproduction: string;
/** Link to an external resource, often the object page on metmuseum.org */
linkResource: string;
/** Date the metadata was last updated */
metadataDate: string;
/** Repository where the object is held (usually "The Metropolitan Museum of Art") */
repository: string;
/** URL to the object's page on metmuseum.org */
objectURL: string;
/** Associated tags or keywords */
tags: Tag[] | null;
/** Wikidata URL for the object */
objectWikidata_URL?: string;
/** Indicates if the object is considered a timeline work */
isTimelineWork: boolean;
/** Gallery number where the object might be displayed */
GalleryNumber: string;
}Retrieves the list of museum departments, including their names and IDs.
Signature:
fetcher.getDepartments(): Promise<DepartmentList>Returns: Promise<DepartmentList>
View DepartmentList & Department Types
export interface Department {
/** A unique identifier for the department */
departmentId: number;
/** The display name of the department */
displayName: string;
}
/** An array of Department objects */
export type DepartmentList = Department[];Performs a search across the collection based on a keyword or query string. Returns the total number of matching objects and their IDs.
Signature:
fetcher.search(q: string, options?: SearchOptions): Promise<SearchResponse>Parameters:
q(string): The search query string (required).options(SearchOptions, optional): An object containing filter parameters.
Returns: Promise<SearchResponse>
View SearchOptions Type
export interface SearchOptions {
/** Set to true to search only for highlighted objects. */
isHighlight?: boolean;
/** Set to true to search only against the title field. */
title?: boolean;
/** Set to true to search only against the subject keyword tags field. */
tags?: boolean;
/** Restricts search to a specific department by ID. */
departmentId?: number;
/** Set to true to search only for objects currently on view. */
isOnView?: boolean;
/** Set to true to search only against the artist name or culture field. */
artistOrCulture?: boolean;
/** Filter by medium. Accepts a single string or an array of strings (e.g., "Paintings", ["Ceramics", "Furniture"]). */
medium?: string | string[];
/** Set to true to search only for objects with images. */
hasImages?: boolean;
/** Filter by geographic location. Accepts a single string or an array of strings (e.g., "Europe", ["France", "Paris"]). */
geoLocation?: string | string[];
/** Start year for date range filter (inclusive). Requires dateEnd. */
dateBegin?: number;
/** End year for date range filter (inclusive). Requires dateBegin. */
dateEnd?: number;
}View SearchResponse Type
export interface SearchResponse {
/** The total number of objects matching the search query */
total: number;
/** An array of object IDs matching the search query. Can be null if no results are found. */
objectIDs: number[] | null; // API documentation notes it can be null
}- Clone the repository:
git clone https://github.com/jwd-gg/met.git cd met - Install dependencies:
bun install
- Build:
bun run build
Contributions are welcome! Please feel free to submit a pull request or open an issue.
This project is licensed under the MIT License. See the LICENSE file for details, or refer to https://choosealicense.com/licenses/mit/.