Uh oh!
There was an error while loading. Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork 0
The Exchange provides an API for searching on and retrieving resources, collections and collection objects. Two endpoints are provided:
The search endpoint performs searches on Exchange items using the same engine and indexes at the site search. The endpoint can return Exchange resources, collections or collection objects. All responses are formatted as JSON.
The search endpoint is invoked using a URL in this format:
https://[server]/api/search/[item_type]/[query]
Where item_type is one of resources, collections or collection_objectsquery should contain search terms.
You can control how many items are returned in a single request using the length option. If omitted a maximum of 10 items are returned. The page option allows you to select which set of limit records to return. Page numbers start at 1. Using limit and page in tandem provides a mechanism for paging through large result sets.
The sort option can be used to control the order of the result set. Possible values are:
title(The item title)idno(Collection object museum identifier)artist(Collection object artist name)created_at(Creation date/time of item)start_date(Collection object date)rating(Average user rating)
When the sort option is omitted, results will be returned sorted by relevance.
Options other than item_type and query can be appended to the URL as parameters. For example, to search on the phrase "Berlin photographs" for collection objects:
https://[server]/api/search/collection_objects/berlin+photographs?sort=start_date&limit=20&page=2
This URL will return the "Berlin photograph" collection object matches sorted by date and starting with the second set of 20. Searches on words or phrases perform a full-text search. Field-level searches, boolean combinations and other options are supported through the Lucene search syntax, described in more detail below
The detail endpoint returns all content for a specific item. Items are selected using numeric ids. These ids are used in Exchange resource URLs and returned by the search service.
The detail endpoint is invoked using a URL in this format:
https://[server]/api/detail/[id]
For example https://[server]/api/detail/10557 will return this JSON:
{
"api_version": 1.0,
"generated": "2020-05-01T11:20:20-04:00",
"data": {
"id": 10557,
"slug": "berlin-nude",
"title": "Berlin Nude ",
"subtitle": "1984/1.277.11",
"copyright_license": "All Rights Reserved",
"copyright_notes": "",
"access": 0,
"forked_from_resource_id": null,
"created_at": "2016-10-04T14:54:56.000-04:00",
"updated_at": "2019-05-27T03:13:30.000-04:00",
"body_text": "<strong>Accession Number</strong><br />1984/1.277.11<br /><br /><strong>Title</strong><br />Berlin Nude <br /><br /><strong>Artist(s)</strong><br /><a href=\"../../quick_search/query?utf8=true&q=artist:"Helmut Newton"\">Helmut Newton</a><br /><br /><strong>Artist Nationality</strong><br /><a href=\"../../quick_search/query?utf8=true&q=artist_nationality:"Australian"\">Australian</a><br /><br /><strong>Object Creation Date</strong><br /><a href=\"../../quick_search/query?utf8=true&q=date_created:"1977"\">1977</a><br /><br /><strong>Medium & Support</strong><br /><a href=\"../../quick_search/query?utf8=true&q=medium:"gelatin silver print on paper"\">gelatin silver print on paper</a><br /><br /><strong>Dimensions</strong><br /> 8 1/16 in x 12 3/16 in (20.48 cm x 30.96 cm)<br /><br /><strong>Credit Line</strong><br /><a href=\"../../quick_search/query?utf8=true&q=credit_line:"Gift of Gerald and Selma Lotenberg"\">Gift of Gerald and Selma Lotenberg</a><br /><br /><strong>Subject matter</strong><br />A photograph from a portfolio of images in which Helmut Newton depicts celebrities, designers and models in highly contrived poses and often placed in decadent scenes. In this photograph, a woman lays in a bed, wearing only a bra. Her head awkwardly rests on pillows as she leans back on one elbow. Her legs disappear under the sheets which are pulled back to display her body. A bedside light increases the sense that her body is distorted.<br /><br /><strong>Physical Description</strong><br />This photograph depicts a nude woman reclining on a bed, smiling and gazing back at the viewer. <br /><br /><strong>Primary Object Classification</strong><br /><a href=\"../../quick_search/query?utf8=true&q=classification:"Photograph"\">Photograph</a><br /><br /><strong>Collection Area</strong><br /><a href=\"../../quick_search/query?utf8=true&q=collection_area:"Photography"\">Photography</a><br /><br /><strong>Rights</strong><br />If you are interested in using an image for a publication, please visit <a href=\"http://umma.umich.edu/request-image\" target=\"_blank\">http://umma.umich.edu/request-image</a> for more information and to fill out the online Image Rights and Reproductions Request Form.",
"author_name": null,
"in_response_to_resource_id": null,
"on_display": false,
"location": null,
"artist": "Helmut Newton",
"start_date": "1977.0101",
"end_date": "1977.1231235959",
"classification": "Photograph",
"additional_classification": "",
"medium": "gelatin silver print",
"support": "paper",
"style": "",
"artist_nationality": "Australian",
"subject_matter": "A photograph from a portfolio of images in which Helmut Newton depicts celebrities, designers and models in highly contrived poses and often placed in decadent scenes. In this photograph, a woman lays in a bed, wearing only a bra. Her head awkwardly rests on pillows as she leans back on one elbow. Her legs disappear under the sheets which are pulled back to display her body. A bedside light increases the sense that her body is distorted.",
"keywords": [
"females",
"nudes",
"bed",
"reclining",
"modern and contemporary art",
"female",
"nudes (representations)",
"reclining",
"beds (furniture)",
"bedrooms",
"sheets (bed coverings)",
"interior spaces (spaces by location)",
"night tables"
],
"type": "Collection object"
}
}The media endpoint returns additional information for media referenced in the search and detail endpoints. Media is selected using numeric media ids return in the other service calls.
The media endpoint is invoked using a URL in this format:
https://[server]/api/media/[id]
For example https://[server]/api/media/68180 will return this JSON:
{
"api_version": 1.0,
"generated": "2020-06-03T12:46:48-04:00",
"data": {
"id": 68180,
"slug": "representation-40694-1",
"resource_id": 7973,
"caption": "<strong>Dmitri Baltermants<br /></strong><strong>Agfa, Berlin<br /></strong>gelatin silver print on paper<br />16 in x 20 in (40.64 cm x 50.8 cm)<br />Gift of Mr. and Mrs. James Agah, Class of 1989 (BBA)",
"copyright_license": "All Rights Reserved",
"copyright_notes": "1",
"access": 1,
"alt_text": "A man in uniform and heavy coat looks to his right as he stands posed next to a broken sign and broken mannequins in the rubble-filled street of Berlin.",
"media_type": "CollectiveaccessLink",
"collection_identifier": "2012/2.77",
"resource_link": "http://exchange.whirl-i-gig.com:8084/resources/7973",
"icon": "http://exchange.whirl-i-gig.com:8084/media/W1siZiIsIjIwMjAvMDUvMjAvczdoMXcxdWF5X2RlZmF1bHQuanBnIl1d?sha=ecfcdcc2cccd79af",
"largeicon": "http://exchange.whirl-i-gig.com:8084/media/W1siZiIsIjIwMjAvMDUvMjAvczdoMXcxdWF5X2RlZmF1bHQuanBnIl1d?sha=ecfcdcc2cccd79af",
"quarter": "http://exchange.whirl-i-gig.com:8084/media/W1siZiIsIjIwMjAvMDUvMjAvczdoMXcxdWF5X2RlZmF1bHQuanBnIl1d?sha=ecfcdcc2cccd79af",
"thumbnail": "http://exchange.whirl-i-gig.com:8084/media/W1siZiIsIjIwMjAvMDUvMjAvczdoMXcxdWF5X2RlZmF1bHQuanBnIl1d?sha=ecfcdcc2cccd79af",
"medium": "http://exchange.whirl-i-gig.com:8084/media/W1siZiIsIjIwMjAvMDUvMjAvczdoMXcxdWF5X2RlZmF1bHQuanBnIl1d?sha=ecfcdcc2cccd79af",
"mediumlarge": "http://exchange.whirl-i-gig.com:8084/media/W1siZiIsIjIwMjAvMDUvMjAvczdoMXcxdWF5X2RlZmF1bHQuanBnIl1d?sha=ecfcdcc2cccd79af",
"large": "http://exchange.whirl-i-gig.com:8084/media/W1siZiIsIjIwMjAvMDUvMjAvczdoMXcxdWF5X2RlZmF1bHQuanBnIl1d?sha=ecfcdcc2cccd79af"
}
}Media URLs are returned for versions at various sizes:
- icon (72px x 72px)
- largeicon (120px x 120px)
- quarter (235px x 235px)
- thumbnail (240px x 200px)
- medium (400px x 400px)
- mediumlarge (800px x 800px)
- large (1000px x 1000px)
- huge (2000px x 2000px)
- realhuge (4000px x 4000px)
- original (a URL to the originally uploaded media)
For collection images, Flickr images and Exchange-hosted files all URLs will point to resources on the Exchange server. For other media, the original URL will point to the media source (Eg. a Youtube link) while the other versions will point to static preview images generated on the Exchange server.
For media with copyright status set to "All Rights Reserved", only media versions less than 1000px in size available.
No authentication is required to use the API. Without authentication only publicly accessible items will be returned. If the API is used within the context of an authenticated session, the API will return any item to which the currently authenticated user has access.
The search endpoint query parameter supports the Lucene search syntax. All Exchange fields are searchable, along with several calculated values:
| Field | Type | Description |
|---|---|---|
| title | text | |
| subtitle | text | |
| physical_description | text | |
| resource_type | integer | Use Resources => 1; Collections => 2; Collection objects => 3 |
| copyright_license | integer | Use All Rights Reserved => 0; Creative Commons by-nc-sa => 1; Creative Commons by-nc => 2; Creative Commons by-nc-nd => 3; Creative Commons by => 4; Creative Commons by-sa => 5; Creative Commons by-nd => 6; No copyright restrictions => 7; United States Government work => 8; Web Use Permitted => 9 |
| copyright_notes | text | |
| body_text | text | The primary text for the resource or collection. For collection objects this field will contain formattted text fully describing the object. Some of this text will be duplicative of other available fields. |
| author_name | text | Name of resource author, if specified. |
| affiliation | text | Affiliation of resource author, if specified. |
| collection_identifier | text | Accession number of collection object. Not set for resources and collections. |
| on_display | integer | May be 0 or 1. 1 indicates item is on display. |
| location | text | |
| artist | text | Name of artists. When multiple artists are associated, names will be returned as a semicolon-separated list. |
| artist_nationality | text | Nationality of artist. When multiple artists are associated, corresponding nationalities will be separated with semicolons. |
| artist_gender | text | Gender of artist. When multiple artists are associated, corresponding genders will be separated with semicolons. |
| classification | text | |
| additional_classification | text | |
| medium | text | |
| support | text | |
| medium_and_support_display | text | Medium and support description for display. |
| style | text | |
| collection_area | text | |
| subject_matter | text | |
| keywords | text | |
| credit_line | text | |
| date_created | text | Historical date of creation for collection objects. Can be year or delimited date. Ex. "1950", "4/1975", "4/1/1975" |
| created | date | Date resource was created. Can be single ISO 8601 year, year-month or year-month-day. Ranges of years or dates may also be specified using providing start and end dates separated with a dash ("-"). Ex. created:2020, created:2018-2020, created:2020-05, created:2020-05-01-2020-06-25. Do not include spaces in date expressions. |
| updated | date | Date resource was lat updated. Uses the same syntax as created for specification of date or date range. |
By default, any text is searched for across all available fields. To restrict a search to a specific field ("title" for instance) prefix the text with the field name an a colon:
title:female
If you are querying on multiple words enclose them with quotes to ensure all words associate with the prefix:
title:"female figure"
When searching on text, multiple words are logically AND'ed together – only records with all of the words are returned. The same holds for field-specific searches. To logically OR searches use the OR operator:
title:"female figure" OR subtitle:"female figure"
In this case, records matching the phrase is either "title" or "subtitle" will be returned.
Wildcard searches can be run on individual terms, using ? to replace a single character, and * to replace any number of characters:
title:"fem*"
Would return any record with a word in the title starting with "fem"
For additional information about search syntax see the Lucene search syntax reference.