Filters


Introduction

With Navigart 3 API, one can filter datas. The API gives you also informations about available filters.

Informations about filters

Informations about filters are available in b aggregations. Here is a standard query to the API :

curl http://api.navigart.fr/123/artworks

And here is the response :

{
         "startIndex": 0,
         "totalCount": 104071,
         "filteredCount": 104071,
         "itemsPerPage": 15,
         "aggregations": {...}
}

The filters informations are available in part aggregations. If you want to know every filters available, you can use jq tool :

curl https://api.navigart.fr/123/artworks | jq '.aggregations | keys'
[
  "authors",
  "collection_department",
  "hanging",
  "image_number",
  "images_set_elements",
  "images_set_header",
  "inventory_number",
  "mode_acq",
  "nationality",
  "rights_management_all",
  "set_type",
  "thema01",
  "title",
  "tree_deposit_from_all",
  "tree_deposit_from_leaf",
  "tree_deposit_from_root",
  "tree_deposit_place_all",
  "tree_deposit_place_leaf",
  "tree_deposit_place_root",
  "tree_domain_all",
  "tree_domain_leaf",
  "tree_domain_root",
  "tree_internal_localization_all",
  "tree_internal_localization_leaf",
  "tree_internal_localization_root",
  "with_text_notes",
  "year",
  "year_acq"
]

You can use each of this information as a filter. You have more informations about one filter. For example, let's see what informations we have about title :

curl https://api.navigart.fr/123/artworks | jq '.aggregations.title'
{
    "displayed_as": "Titre",
    "pos": 4,
    "total": 19449,
    "terms": [
        {
        "key": "Sans titre",
        "doc_count": 3011
        },
        {
        "key": "(Sans titre)",
        "doc_count": 1364
        },
        {
        "key": "Untitled",
        "doc_count": 91
        },
        {
        "key": "Sans Titre",
        "doc_count": 52
        },
        {
        "key": "ROMAN OPALKA / 1965 / 1 - ∞",
        "doc_count": 50
        },
        {
        "key": "12 ans après",
        "doc_count": 34
        }
    ]
}

Here we have :

Filtering datas

Filtering datas is done by constructing a specific URL :

https://api.navigart.fr/123/artworks?filters=filterTitle:filterKey

where filterTitle must be replaced by your filter title (title, authors, …) and filterKey must be replaced by your filter key.

Examples :

Specific filters

On some filters, you need to add some things to treat correctly the filter keys. For technical reasons, we have add prefix or suffix to the keys. You will see it on filter for authors and dates.

Combining filters

You can combine filters. For example, you may want to get "artworks with one author is X and of the domain Y". This can be done by add more than one filter : curl https://api.navigart.fr/123/artworks?filters=domain:Photographie,,authors:CLOSKY+Claude↹CLOSKY+Claude

When you combine differents filters, the result is equivalent to an AND. For example : filters=domain:Photographie,,authors:CLOSKY+Claude↹CLOSKY+Claude,,collection:Frac+Corse is equivalent to "all artworks of domain Photographie and with one author is Claude CLOSKY and in collection Frac Corse"

When you combine same filter, use || between keys of the filter and don't repeat the filter name. For example : filters=authors:CLOSKY+Claude↹CLOSKY+Claude,,collection:Frac+Corse,,collection:Frac+Champagne-Ardenne gives no result because it is equivalent to "all artworks with one author is Claude CLOSKY and in collection Frac Corse and in collection Frac Champagne-Ardenne". It gives no result because one artwork could not been in two differents collections in same time.

When you combine same filter, use || between keys of the filter : the result is equivalent to an OR. For example : filters=authors:CLOSKY+Claude↹CLOSKY+Claude,,collection:Frac+Corse||Frac+Champagne-Ardenne is equivalent to "all artworks with one author is Claude CLOSKY and (in collection Frac Corse or in Frac Champagne-Ardenne)"

Pagination in filter

You can show all keys available for one filter name by using pagination. By default, only first 6 values are available for each filter name.

Fisrt, you can set size=0 to your query to only have informations about filters. By setting size to 0, you ask the API to not giving you results and this is better for performance from the API point of view (it hasn't to get informations about artworks), from the bandwith point of view (data volume of results may be heavy) and your application point of view (you don't have to treat datas you don't need).

Then you can ask details about one filter name, for example authors : https://api.navigart.fr/123/artworks?size=0&term=authors&term_from=0&term_order=count:desc&term_size=12 Here are the details of the query : * size=0 : we don't want results to optimize the response * term=authors : we ask for filter keys about filter name authors * term_from=0 : we want filter keys beginning at 0 (so, the first page) * term_size=12 : each page should have 12 filter keys * term_order=count:desc : we sort datas with the number of artworks associated to this filter key If you want to have the second page of the filter keys, increases the term_from by term_size : https://api.navigart.fr/123/artworks?size=0&term=authors&term_from=12&term_order=count:desc&term_size=12 And the third page : https://api.navigart.fr/123/artworks?size=0&term=authors&term_from=24&term_order=count:desc&term_size=12

Search in filter

You can also search in filter keys for a filter name, for exame, searching "claude" in authors names : https://api.navigart.fr/123/artworks?size=0&term=authors&term_from=0&term_order=count:desc&term_size=12&term_word=claude Just use term_word and your term you want to search.

Contact us

You may contact us by sending an email to aide@videomuseum.fr