NAV
shell

Introduction

Welcome to the RMN-GP API documentation! You will soon be able to use our API to access RMN-GP API endpoints, and retrieve information in the JSON format on various artworks, artists, and related pictures in our database.

This documentation should help you discover our API, and includes some examples using curl, on the right-most pane. You can also explore the API live using our Javascript console.

Versioning

All API calls must specify which API version to use. This version identifier ensures that API will not introduce major changes for the given version.

You can get the last API version by requesting the root API endpoint: https://api.art.rmngp.fr/art

Then prefix all paths with this version number, for example: https://api.art.rmngp.fr/v1/api_endpoint_here.

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/"

The above command returns JSON structured like this:



Authentication

To be authorized, you will need to include the key in HTTP request headers:

curl -H "ApiKey: demo" \
     "https://api_endpoint_here"

Make sure to replace demo with your API key.

RMN-GP uses API keys to allow access to the API. You will soon be able to request one on our partners’ site.

RMN-GP expects the API key to be included in all API requests to the server in a HTTP header that looks like the following:

ApiKey: demo

Errors

The RMN-GP API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The requested resource is not accessible
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The requested resource has been removed from our servers
418 I’m a teapot
429 Too Many Requests – You’re requesting too many resources! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily off-line for maintenance. Please try again later.

Images

Some endpoints return images, here the stucture:

Example

{
  "id": 167,
  "identifier": "06-528589",
  "urls": {
    "original": "https://api.art.rmngp.fr/v1/images/1/167?t=thisisaprivatetoken",
    "small": {
      "width": 95,
      "height": 95,
      "type": "resize",
      "url": "https://api.art.rmngp.fr/v1/images/1/167/s?t=thisisaprivatetoken"
    },
    "thumbnail": {
      "width": 190,
      "height": 190,
      "type": "resize",
      "url": "https://api.art.rmngp.fr/v1/images/1/167/t?t=thisisaprivatetoken"
    },
    "medium": {
      "width": 379,
      "height": 379,
      "type": "resize",
      "url": "https://api.art.rmngp.fr/v1/images/1/167/m?t=thisisaprivatetoken"
    },
    "large": {
      "width": 758,
      "height": 758,
      "type": "resize",
      "url": "https://api.art.rmngp.fr/v1/images/1/167/l?t=thisisaprivatetoken"
    }
  }
}

Search

Response

The response consists of 2 sections:

Hits

This section contains the results of your search. Check the Elastic Search documentation for more informations.

In short, this section is structured like this:

Facets

This section contains the facets related to your search. Each aggregation is defined by a key, and contains many buckets. Buckets are the available facets for the current search.

Facet structure looks like this:

Pagination

When listing or searching documents, the API always returns paginated results. The default is to return 10 results per page.

The total number of results matching a Query is indicated by the total key, immediately under the hits key.

To get another results page, just add these parameters:

To change page, simply pass a page parameter to your request URL.

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works?page=2"

Sample results, matching a total of 42 documents.

{
  "hits": {
    "total": 42,
    "hits": []
  }
}

Full text

When you want to search for documents, you can perform a full text using the q parameter.

This parameter uses the Query String Query format of Elastic search API.

Here are some examples.

If you want to search on all fields, just provide a string: la joconde.

curl -H "ApiKey: demo" \
     'https://api.art.rmngp.fr/v1/works.json?q=la%20joconde'

curl -H "ApiKey: demo" \
     'https://api.art.rmngp.fr/v1/works.json?q=la%20joconde&lang=fr'

By default, the search is made on all tha available languages. You can limit the search to a specific language by using the lang parameter. It can improve the relevancy of results by using a more precise analyzer.

Matching a field

Alternatively, you can select a field to search for, if you want to match an exact value on only the title, use title:"la joconde". You can use this to limit the results to a work with a specific id, like this: id:36238.

curl -H "ApiKey: demo" \
     'https://api.art.rmngp.fr/v1/works.json?q=title:"la%20joconde"'

curl -H "ApiKey: demo" \
     'https://api.art.rmngp.fr/v1/works.json?q=id:36238'

The full text search is good but sometime you want something more precise when you do a search in an API : it’s possible.

For exemple, you want to search la joconde but you only want to have result that are drawed : you can pass "joconde AND techniques.name=dessin" in the q parameter.

You can do that with every terms of the works like periods, keywords, authors,…

You can also use the operand OR For exemple you can use "joconde OR collection=estampes"

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works.json?q=la%20joconde%20AND%20techniques%3Ddessin"

Filtering facets

On works, authors and selections endpoints, facets are availables.

To filter on a facet, just add a facets[facet_name]=facet_value params to the query string.

By default, only 10 items per facet are returned by the api. If you want more, use the facet pagination.

For example, we have the following facets returned by the works endpoint:

  {
    "sources": {
      "buckets": [
        {
          "key": "INHA",
          "doc_count": 5977,
          "link": "https://api.art.rmngp.fr/v1/works?api_key=demo&facets%5Bsources%5D=INHA"
        },
        {
          "key": "BPK",
          "doc_count": 2,
          "link": "https://api.art.rmngp.fr/v1/works?api_key=demo&facets%5Bsources%5D=BPK"
        },
        {
          "key": "NATIONAL GALLERY OF LONDON",
          "doc_count": 1,
          "link": "https://api.art.rmngp.fr/v1/works?api_key=demo&facets%5Bsources%5D=NATIONAL+GALLERY+OF+LONDON"
        },
        {
          "key": "RMN",
          "doc_count": 1,
          "link": "https://api.art.rmngp.fr/v1/works?api_key=demo&facets%5Bsources%5D=RMN"
        },
        {
          "key": "RMN (musée du Louvre)",
          "doc_count": 1,
          "link": "https://api.art.rmngp.fr/v1/works?api_key=demo&facets%5Bsources%5D=RMN+%28mus%C3%A9e+du+Louvre%29"
        }
      ]
    }
  }

To filter works on the “RMN” source, add this params to the query string: facets[sources]=RMN

Works

Definition

Attributes

Associations

Get All Works

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works"

The above command returns JSON structured like this:



This endpoint retrieves all artworks.

HTTP Request

GET https://api.art.rmngp.fr/v1/works

Query Parameters

Parameter Default Description
q Filter results matching this query
lang Limit the research to fields in this language (better relevance)
exists Limit the research to works with these fields
exclude[keywords.name.fr][] Array of keywords to exclude
exclude[techniques.name.fr][] Array of techniques to exclude
exclude[authors.name.fr][] Array of authors to exclude
exclude[periods.name.fr][] Array of periods to exclude
exclude[collections.name.fr][] Array of collections to exclude
exclude[geographies.name.fr][] Array of geographies to exclude
exclude[location.name.fr][] Array of locations to exclude
exclude[images.photographer.name][] Array of photographer to exclude
exclude[schools.name.fr][] Array of schools to exclude
exclude[images.source.name][] Array of source to exclude
exclude[styles.name.fr][] Array of styles to exclude
sort Field used to sort results
order asc Sorting order, desc or asc.
page 1 Results page offset
per_page 10 Number of results per page
facet_page 1 Facet page offset
facet_per 10 Number of facets per page
facets[collections] Filter on a collection facet
facets[locations] Filter on a location facet
facets[authors] Filter on a author facet
facets[periods] Filter on a period facet
facets[techniques] Filter on a technique facet
facets[styles] Filter on a style facet
facets[schools] Filter on a schools facet
facets[geographies] Filter on a geography facet
facets[colors] Filter on a color facet
filters[images.identifier] Filter on an image identifier

For more specific search see Search

Get a specific work by its ID or slug

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works/:id"

The above command returns JSON structured like this:



This endpoint retrieves a specific work by its slug.

HTTP Request

GET https://api.art.rmngp.fr/v1/works/:id

Query Parameters

Parameter Default Description
id A work ID or slug
count_me[user_id] ID of user visiting the page
count_me[session_id] Session ID of user visiting the page

Get suggested works

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works/suggested"

The above command returns JSON structured like this:



This endpoint retrieves a list of suggested works. You can provide a work_id to get contextual suggestions.

HTTP Request

`GET https://api.art.rmngp.fr/v1/works/suggested

Query Parameters

Parameter Default Description
id A work id
slug A work slug
exists Limit the research to works with these fields
exclude[keywords.name.fr][] Array of keywords to exclude
exclude[techniques.name.fr][] Array of techniques to exclude
exclude[authors.name.fr][] Array of authors to exclude
exclude[periods.name.fr][] Array of periods to exclude
exclude[collections.name.fr][] Array of collections to exclude
exclude[geographies.name.fr][] Array of geographies to exclude
exclude[location.name.fr][] Array of locations to exclude
exclude[images.photographer.name][] Array of photographer to exclude
exclude[schools.name.fr][] Array of schools to exclude
exclude[images.source.name][] Array of source to exclude
exclude[styles.name.fr][] Array of styles to exclude
page 1 Results page offset
per_page 10 Number of results per page

Aggregations

The works endpoint can also decorate the response with some aggregation computations. It works with the aggregation framework from Elasticsearch.

For example, you can have some stats on the dimensions of the works painted by Picasso. (see: aggregations.works_width and aggregations.works_height)

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works?q=Picasso&aggregates[][name]=works_width&aggregates[][type]=stats&aggregates[][field]=width&aggregates[][name]=works_height&aggregates[][type]=stats&aggregates[][field]=height"


The citizenship of the authors for the 19th century. (see: aggregations.authors_citizenship)

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works?aggregates[][name]=authors_citizenship&aggregates[][type]=terms&aggregates[][field]=authors.citizenship&facets[periods]=19e+siècle"


Most fields are tokenized and stemmed for a better full-text search. It can give weird results for aggregation. In that case, you can try to append .raw to the field name.

Parameters

To add an aggregation, you have to give 3 parameters:

Type Description
min Returns the minimum value among the numeric values extracted from the aggregated documents
max Returns the maximum value among numeric values
sum Sums up numeric values
avg Computes the average of numeric values
stats Computes stats over numeric values (min, max, sum, avg and count)
extended_stats An extended version of the stats aggregation, where additional metrics are added such as sum_of_squares, variance and std_deviation
cardinality Calculates an approximate count of distinct values
value_count Counts the number of values that are extracted from the aggregated documents
missing Counts all documents in the current document set context that are missing a field value
percentiles Calculates percentiles over numeric values (1%, 5%, 25%, 50%, 75%, 95%, 99%)
terms A multi-bucket value source based aggregation where buckets are dynamically built - one per unique value
significant_terms Returns interesting or unusual occurrences of terms in a set (experimental!)
histogram Dynamically builds fixed size (a.k.a. interval) buckets over the values
date_histogram Same as histogram, but can use interval with not a fixed size (a month or a year for example)

For histograms, a fourth parameter, interval, will be given.

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works?aggregates[][name]=histogram&aggregates[][type]=date_histogram&aggregates[][field]=date.estimated_day&aggregates[][interval]=month"

The above command returns JSON structured like this:



          

Authors

List all authors present on the API.

Definition

Attributes

Associations

Get All Authors

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/authors"

The above command returns JSON structured like this:



This endpoint retrieves all know authors.

HTTP Request

GET https://api.art.rmngp.fr/v1/authors

Query Parameters

Parameter Default Description
q Filter results matching this query
sort Field used to sort results
order asc Sorting order, desc or asc.
page 1 Results page offset
per_page 10 Number of results per page
facet_page 1 Facet page offset
facet_per 10 Number of facets per page
facets[collections] Filter on a collection facet
facets[locations] Filter on a location facet
facets[periods] Filter on a period facet
facets[techniques] Filter on a technique facet
facets[geographies] Filter on a geography facet

For more specific search see Search

Thesaurus

Get all resources

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/collections"

The above command returns JSON structured like this:



Thesaurus consists of several types of resources that are searchable in the same way.

HTTP Request

GET https://api.art.rmngp.fr/v1/thesaurus/$resource_type

Where $resource_type is one of:

Query Parameters

Parameter Default Description
q Filter results matching this query
page 1 Results page offset
per_page 10 Number of results per page

For more specific search see Search

Collections

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/collections"

The above command returns JSON structured like this:



Collections are arbitrary groups of works.

Definition

Attributes

Get All Collections

This endpoint retrieves all known collections.

HTTP Request

GET https://api.art.rmngp.fr/v1/thesaurus/collections

Query Parameters

Parameter Default Description
q Filter results matching this query
filters[level] Filter on a specific level of the thesaurus hierarchy
page 1 Results page offset
per_page 10 Number of results per page

For more specific search see Search

Geographies

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/geographies"

The above command returns JSON structured like this:



Geographies are places in the world where the works was done or founded.

Definition

Attributes

Get All Geographies

This endpoint retrieves all know geographies.

HTTP Request

GET https://api.art.rmngp.fr/v1/thesaurus/periods

Query Parameters

Parameter Default Description
q Filter results matching this query
filters[level] Filter on a specific level of the thesaurus hierarchy
page 1 Results page offset
per_page 10 Number of results per page

For more specific search see Search

Keywords

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/keywords"

The above command returns JSON structured like this:



Keywords contain all the keyword that has no special type.

Definition

Attributes

Get All keywords

This endpoint retrieves all keywords.

HTTP Request

GET https://api.art.rmngp.fr/v1/thesaurus/keywords

Query Parameters

Parameter Default Description
q Filter results matching this query
filters[level] Filter on a specific level of the thesaurus hierarchy
page 1 Results page offset
per_page 10 Number of results per page

For more specific search see Search

Locations

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/locations"

The above command returns JSON structured like this:



Locations are the differents museeum where the works are.

Definition

Attributes

Get All Locations

This endpoint retrieves all know locations.

HTTP Request

GET https://api.art.rmngp.fr/v1/thesaurus/locations

Query Parameters

Parameter Default Description
q Filter results matching this query
page 1 Results page offset
per_page 10 Number of results per page

For more specific search see Search

Periods

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/periods"

The above command returns JSON structured like this:



Periods can be a century, an age, or a period.

Definition

Attributes

Get All Periods

This endpoint retrieves all know periods.

HTTP Request

GET https://api.art.rmngp.fr/v1/thesaurus/periods

Query Parameters

Parameter Default Description
q Filter results matching this query
filters[level] Filter on a specific level of the thesaurus hierarchy
page 1 Results page offset
per_page 10 Number of results per page

For more specific search see Search

Photographers

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/photographers"

The above command returns JSON structured like this:



Authors of the many images available through the API.

Definition

Attributes

Get All Photographers

This endpoint retrieves all know photographers.

HTTP Request

GET https://api.art.rmngp.fr/v1/thesaurus/photographers

Query Parameters

Parameter Default Description
q Filter results matching this query
page 1 Results page offset
per_page 10 Number of results per page

For more specific search see Search

Schools

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/schools"

The above command returns JSON structured like this:



Schools are artistic schools.

Definition

Attributes

Get All Schools

This endpoint retrieves all know schools.

HTTP Request

GET https://api.art.rmngp.fr/v1/thesaurus/schools

Query Parameters

Parameter Default Description
q Filter results matching this query
filters[level] Filter on a specific level of the thesaurus hierarchy
page 1 Results page offset
per_page 10 Number of results per page

For more specific search see Search

Sources

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/sources"

The above command returns JSON structured like this:



Sources are the museum where the works come from : you can also find the copyright in that part.

Definition

Attributes

Get All Sources

This endpoint retrieves all know sources.

HTTP Request

GET https://api.art.rmngp.fr/v1/thesaurus/sources

Query Parameters

Parameter Default Description
q Filter results matching this query
page 1 Results page offset
per_page 10 Number of results per page

For more specific search see Search

Styles

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/styles"

The above command returns JSON structured like this:



Styles of the many works available through the API.

Definition

Attributes

Get All Styles

This endpoint retrieves all know collections.

HTTP Request

GET https://api.art.rmngp.fr/v1/thesaurus/collections

Query Parameters

Parameter Default Description
q Filter results matching this query
filters[level] Filter on a specific level of the thesaurus hierarchy
page 1 Results page offset
per_page 10 Number of results per page

For more specific search see Search

Techniques

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/techniques"

The above command returns JSON structured like this:



Techniques used by many works available through the API.

Definition

Attributes

Get All Techniques

This endpoint retrieves all know techniques.

HTTP Request

GET https://api.art.rmngp.fr/v1/thesaurus/techniques

Query Parameters

Parameter Default Description
q Filter results matching this query
filters[level] Filter on a specific level of the thesaurus hierarchy
page 1 Results page offset
per_page 10 Number of results per page

For more specific search see Search

Users

The users API allows partners to create, and destroy user accounts.

Create a user account

Partners with an API access are allowed to create user accounts.

HTTP Request

POST https://api.art.rmngp.fr/v1/users

Parameters

Parameter Default Description
name user’s name (mandatory).
email user’s email which must be unique in the whole API (mandatory).
password user’s password: it must be at least 8 characters (mandatory).
firstname user’s firstname.
lastname user’s lastname.
newsletter_optin false Newsletter opt in.
language fr user’s firstname.
avatar user avatar file

HTTP Response

Upon successful creation, the server replies with a 201 HTTP status code, and returns the newly created user in JSON format. Any other status code indicate a failure to create the user.

curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/users' -XPOST \
     -d'name=User%20name&email=user@example.com&password=password'

On success, the above command results in a 201 HTTP code, and returns JSON structured like this:

{
    "id":               1,
    "email":            "user@example.com",
    "name":             "User",
    "firstname":        "Foo",
    "lastname":         "Bar",
    "partner_id":       1,
    "newsletter_optin": true,
    "language":         "fr",
    "created_at":       "2014-09-01T00:00:00.42Z",
    "updated_at":       "2014-09-01T00:00:00.42Z",
    "avatar": {
      "thumb": "http://example.com/avatar_thumb.jpg",
      "medium": "http://example.com/avatar_medium.jpg",
      "big": "http://example.com/avatar_big.jpg"
    }
}

If your request contains errors, you will receive a 400 HTTP status code, and a JSON array listing the detected errors. For example:

[
  ["email",    "is missing"],
  ["password", "is missing"]
]

Update a user account

Partners with an API access are allowed to update user accounts.

HTTP Request

PUT https://api.art.rmngp.fr/v1/users/:id

Parameters

Parameter Default Description
name user’s name.
email user’s email which must be unique in the whole API.
password user’s password: it must be at least 8 characters.
firstname user’s firstname.
lastname user’s lastname.
newsletter_optin false Newsletter opt in.
language fr user’s firstname.
avatar user avatar file

HTTP Response

Upon successful update, the server replies with a 20O HTTP status code, and returns the newly updated user in JSON format. Any other status code indicate a failure to update the user.

curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/users/1' -XPUT \
     -d'name=User%20name&email=user@example.com&password=password'

On success, the above command results in a 200 HTTP code, and returns JSON structured like this:

{
    "id":               1,
    "email":            "user@example.com",
    "name":             "User",
    "firstname":        "Foo",
    "lastname":         "Bar",
    "partner_id":       1,
    "newsletter_optin": true,
    "language":         "fr",
    "created_at":       "2014-09-01T00:00:00.42Z",
    "updated_at":       "2014-09-01T00:00:00.42Z",
    "avatar": {
      "thumb": "http://example.com/avatar_thumb.jpg",
      "medium": "http://example.com/avatar_medium.jpg",
      "big": "http://example.com/avatar_big.jpg"
    }
}

Destroy a user account

User accounts created by a partner can be destroyed by the same partner, identified by their API key.

HTTP Request

DELETE https://api.art.rmngp.fr/v1/users/:id

HTTP Response

The server should reply with a 200 HTTP status code when the user is successfully destroyed.

curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/users/1' -XDELETE

On success, the above command results in a 200 HTTP code, and returns the JSON representation of the destroyed user. For example:

{
    "id":         1,
    "name":       "User name",
    "partner_id": 1,
    "email":      "user@example.com",
    "created_at": "2014-09-01T00:00:00.42Z",
    "updated_at": "2014-09-01T00:00:00.42Z",
    "avatar": {
      "thumb": "http://example.com/avatar_thumb.jpg",
      "medium": "http://example.com/avatar_medium.jpg",
      "big": "http://example.com/avatar_big.jpg"
    }
}

Authenticate a user account

Partners with an API access are allowed to authenticate user accounts.

HTTP Request

POST https://api.art.rmngp.fr/v1/users/authenticate

Parameters

Parameter Default Description
email “” user’s email (mandatory).
password “” user’s password (mandatory).

HTTP Response

Upon successful authentication, the server replies with a 200 HTTP status code, and returns the corresponding user in JSON format. Any other status code indicate a failure to authenticate the user.

curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/users/authenticate' -XPOST \
     -d'email=user@example.com&password=password'

On success, the above command results in a 200 HTTP code, and returns JSON structured like this:

{
    "id":         1,
    "name":       "User name",
    "partner_id": 1,
    "email":      "user@example.com",
    "created_at": "2014-09-01T00:00:00.42Z",
    "updated_at": "2014-09-01T00:00:00.42Z",
    "avatar": {
      "thumb": "http://example.com/avatar_thumb.jpg",
      "medium": "http://example.com/avatar_medium.jpg",
      "big": "http://example.com/avatar_big.jpg"
    }
}

Selections

A selection, or selection folder, allows a user to select and organize artworks found on the API.

There is no limit to the number of selections created for a particular user, and there is no limit to the number of artworks that a selection may contain.

List selections

HTTP Request

GET https://api.art.rmngp.fr/v1/selections

Query Parameters

Parameter Default Description
user_id Which user’s selections should we show?
page 1 Results page offset
per_page 10 Number of results per page
tags comma separated list of tags
works[include] Include works in results?
works[q] Search for works
works[lang] fr Return works facets for this language (fr, en, de)
works[sort] Sort works
works[per_page] 1 Number of works per page
works[page] 10 Works page offset
works[facet_per] 1 Number of works facets per page
works[facet_page] 10 Works facets page offset
works[facets][collections] Filter works on a collection facet
works[facets][locations] Filter works on a location facet
works[facets][authors] Filter works on a author facet
works[facets][periods] Filter works on a period facet
works[facets][techniques] Filter works on a technique facet
works[facets][styles] Filter works on a style facet
works[facets][schools] Filter works on a school facet
works[facets][geographies] Filter works on a geography facet
images[include] Include images in results?
images[q] Search for images
images[lang] fr Return images facets for this language (fr, en, de)
images[sort] Sort images
images[per_page] 1 Number of images per page
images[page] 10 Works page offset
images[facet_per] 1 Number of images facets per page
images[facet_page] 10 Works facets page offset
images[facets][collections] Filter images on a collection facet
images[facets][locations] Filter images on a location facet
images[facets][authors] Filter images on a author facet
images[facets][periods] Filter images on a period facet
images[facets][techniques] Filter images on a technique facet
images[facets][styles] Filter images on a style facet
images[facets][schools] Filter images on a school facet
images[facets][geographies] Filter images on a geography facet

HTTP Response

On success, the server replies with a 200 HTTP status code, and returns a list of selections in JSON.

curl -H'ApiKey: demo' 'https://api.art.rmngp.fr/v1/selections'

On success, the above command should yield a JSON array, structured as follows:



If you pass the include[works]=true (and/or include[images]=true) parameter, you should get a JSON array with the following structure (the works and images keys are added):



Create a selection

HTTP Request

POST https://api.art.rmngp.fr/v1/selections

Parameters

Parameter Default Description
name Selection’s name (mandatory)
description Selection’s description
user_id Selection’s owner (mandatory)
work_ids Array of work IDs to associate
image_ids Array of image IDs to associate

HTTP Response

Upon successful creation, the server replies with a 201 HTTP status code, and returns the newly created selection in JSON format. Any other status code indicate a failure to create the selection.

curl -H'ApiKey: demo' \
  'https://api.art.rmngp.fr/v1/selections' -XPOST -d'name=example&user_id=1'

On success, the above command should yield a JSON object, structured as follows:

{
    "id":           1,
    "name":         "example",
    "description":  "Example",
    "user_id":      1,
    "default":      true,
    "updated_at":   "2014-09-01T00:00:00.42Z",
    "created_at":   "2014-09-01T00:00:00.42Z",
    "tags":         "Foo,Bar"
}

Update a selection

HTTP Request

PUT https://api.art.rmngp.fr/v1/selections/:id

Parameters

Parameter Default Description
id Selection ID (mandatory)
name Selection’s name
description Selection’s description
user_id Selection’s owner (mandatory)
work_ids Array of work IDs to associate
image_ids Array of image IDs to associate

HTTP Response

Upon successful update, the server replies with a 200 HTTP status code, and returns the updated selection in JSON format. Any other status code indicate a failure to update the selection.

curl -H'ApiKey: demo' \
  'https://api.art.rmngp.fr/v1/selections/:id' -XPUT -d'name=example&user_id=1'

On success, the above command should yield a JSON object, structured as follows:

{
    "id":           1,
    "name":         "example",
    "description":  "Example",
    "user_id":      1,
    "default":      true,
    "updated_at":   "2014-09-01T00:00:00.42Z",
    "created_at":   "2014-09-01T00:00:00.42Z",
    "tags":         "Foo,Bar"
}

Destroy a selection

HTTP Request

DELETE https://api.art.rmngp.fr/v1/selections/:id

HTTP Response

The server should reply with a 200 HTTP status code, when the selection is successfully destroyed.

curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/selections/1' -XDELETE

On success, the above command results in a 200 HTTP code, and returns the JSON representation of the destroyed selection folder. For example:

{
    "id":           1,
    "name":         "example",
    "description":  "Example",
    "user_id":      1,
    "default":      true,
    "updated_at":   "2014-09-01T00:00:00.42Z",
    "created_at":   "2014-09-01T00:00:00.42Z",
    "tags":         "Foo,Bar"
}

Get a selection

The above command returns JSON structured like this:



HTTP Request

GET https://api.art.rmngp.fr/v1/selections/:id

Query Parameters

Parameter Default Description
id Selection ID (mandatory)
works[include] Include works in results?
works[q] Search for works
works[lang] fr Return works facets for this language (fr, en, de)
works[sort] Sort works
works[per_page] 1 Number of works per page
works[page] 10 Works page offset
works[facet_per] 1 Number of works facets per page
works[facet_page] 10 Works facets page offset
works[facets][collections] Filter works on a collection facet
works[facets][locations] Filter works on a location facet
works[facets][authors] Filter works on a author facet
works[facets][periods] Filter works on a period facet
works[facets][techniques] Filter works on a technique facet
works[facets][styles] Filter works on a style facet
works[facets][schools] Filter works on a school facet
works[facets][geographies] Filter works on a geography facet
images[include] Include images in results?
images[q] Search for images
images[lang] fr Return images facets for this language (fr, en, de)
images[sort] Sort images
images[per_page] 1 Number of images per page
images[page] 10 Works page offset
images[facet_per] 1 Number of images facets per page
images[facet_page] 10 Works facets page offset
images[facets][collections] Filter images on a collection facet
images[facets][locations] Filter images on a location facet
images[facets][authors] Filter images on a author facet
images[facets][periods] Filter images on a period facet
images[facets][techniques] Filter images on a technique facet
images[facets][styles] Filter images on a style facet
images[facets][schools] Filter images on a school facet
images[facets][geographies] Filter images on a geography facet

HTTP Response

The server should reply with a 200 HTTP status code.

curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/selections/1' -XGET

On success, the above command results in a 200 HTTP code, and returns the JSON representation of this selection folder. For example:



Add a work or an image to a selection

HTTP Request

POST https://api.art.rmngp.fr/v1/selections/:id/:document_type

Parameters

Parameter Default Description
id Selection ID (mandatory).
document_type Type of document to add, images or works (mandatory).
document_id Document’s ID on the API (mandatory).
position unsigned integer to choose the entry’s position (mandatory).

HTTP Response

Upon successful creation, the server replies with a 201 HTTP status code, and returns a JSON object with the selected work ID, and its version number.

Any other status code indicate a failure to create the selection.

curl -H'ApiKey: demo' \
  'https://api.art.rmngp.fr/v1/selections/1/works' \
  -XPOST -d'work_id=42&position=1'

On success, the above command results in a 201 HTTP status code, and should yield a JSON object, structured as follows:

{
    "id":             1,
    "selection_id":   1,
    "document_id":    42,
    "document_type":  "Work",
    "version_id":     1,
    "position":       1
}

Add an work or and image to the user default selection

HTTP Request

POST https://api.art.rmngp.fr/v1/selections/:user_id/default/:document_type

Parameters

Parameter Default Description
user_id User ID (mandatory).
document_type Type of document to add, images or works (mandatory).
document_id Document’s ID on the API (mandatory).
position unsigned integer to choose the entry’s position (mandatory).

HTTP Response

Upon successful creation, the server replies with a 201 HTTP status code, and returns a JSON object with the selected work ID, and its version number.

Any other status code indicate a failure to create the selection.

curl -H'ApiKey: demo' \
  'https://api.art.rmngp.fr/v1/selections/42/default/works' \
  -XPOST -d'work_id=42&position=1'

On success, the above command results in a 201 HTTP status code, and should yield a JSON object, structured as follows:

{
    "id":             1,
    "selection_id":   1,
    "document_id":    42,
    "document_type":  "Work",
    "version_id":     1,
    "position":       1
}

Remove a work or an image from a selection

HTTP Request

DELETE https://api.art.rmngp.fr/v1/selections/:selection_id/:document_type/:id

Parameters

Parameter Default Description
document_type Type of document to add, images or works (mandatory).
document_id Document’s ID on the API (mandatory).

HTTP Response

The server should reply with a 200 HTTP status code, when the work is successfully removed from the selection.

If you try to delete from a selection folder that does not exist, or a work that is not part of the selection, then the server replies with a 404 HTTP error code.

curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/selections/1/works/42' -XDELETE

On success, the above command results in a 200 HTTP code, and returns the JSON representation of the destroyed entry. For example:

{
    "id":             1,
    "selection_id":   1,
    "document_id":    42,
    "document_type":  "Work",
    "version_id":     1,
    "position":       1
}

Autocomplete

Get suggestions for a string pattern, usefull for auto-completions.

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/autocomplete?q=jacob"

The above command returns JSON structured like this:



HTTP Request

GET https://api.art.rmngp.fr/v1/autocomplete

Query Parameters

Parameter Default Description
q Pattern to search
lang fr Specific language. fr and en are available
types work,author,location,period,technique Specific types of items to search. work, author, period, technique, location avalaible
per 5 Number of results to return.