API: faceting

This page is used as a temporary work area for sketching the new (2023) facets API as described in #10995. So far API have been designed and refined in the main description of that issue, but this is making he following coments no longer related to it, so this is the reference page, that will be moved in the geonode doc files once this API is stable enough.

API endpoints

[API_PATH]/facets

Purpose

Returns a list of available facets.

GET params

• include_topics: bool, 0..1: include first n topics to every facet
• filter: string, 0..N: if include_topics, this field is used to pre-filter resources (see pre-filtering)
• lang: bool, 0..1: return localized labels if possible
• add_links: bool, 0..1: add links to facets endpoint

Payload

The returned payload is a dict:

 {"facets": [facet,...]}

[API_PATH]/facets/<facet_name>

Purpose

Returns info for the requested facet.
By default the first page of topics is included.

GET params

• page/page_size: (int,int), 0..1: topics pagination params
• filter: string, 0..N: used to pre-filter resources (see pre-filtering)
• topic_contains: string, 0..1: used to pre-filter topics with a string
• lang: str (2 letters), 0..1: return localized labels if possible
• add_links: bool, 0..1: add links to prev/next pages
• keys: string, 0..N: only returns topics with given keys, even if their count is 0

[API_PATH]/facets/<facet_name>/topics

Purpose

Returns labels for the requested topics.

GET params

• key: string, 1..N: the topic key of which we want the label
• lang: str (2 letters), 0..1: return localized labels if possible

Payload

A JSON dict:

• topics: as per /facets/<facet_name>, but without pagination, since we're getting only the requested info.
  • items: as per /facets/<facet_name>, without count since we're only getting localizion info
    • key: as per /facets/<facet_name>
    • label: as per /facets/<facet_name>
    • is_localized: as per /facets/<facet_name>

Pre-filtering

The filter parameters are parsed by the DREST library and are in the form filter{FIELD_EXPRESSION}=VALUE, for instance:

• filter{metadata_only}=false
• filter{date.gte}=2023-06-01T00:00:00

Payloads

• facet is a dict:

  key	type	opt	description
  name	str	no	Name of the facet (to be used in the /facet/<facet_name> entrypoint)
  filter key	str	no	string to be used as KVP param in the resources query
  label	str	no	Label for the facet (could be localized)
  is_localized	str	yes	If exists and it's true, tells that the label is already translated and requires no further localization actions by the client
  type	enum	no	Type of facet, may be used by the client for rendering. So far region, category, people, thesaurus
  hierarchical	bool	yes no	Tells if the facet has nested elements (don't know if this is really useful)
  order	int	opt	May be useful for telling the UI how to present the facets thesauri have their own internal ordering (where can it be configured?)
  link	url	opt	link to the facet - /facets: requested using the add_links param - /facets/<ID>: N/A
  prev	url	opt	link to previous paginated set of topics - /facets: N/A - /facets/<ID>: requested using the add_links param
  next	url	opt	link to next paginated set of topics - /facets: N/A - /facets/<ID>: requested using the add_links param
  topics	dict	opt (see descr)	Info on topic set. - /facets: only present if include_topics requested - /facets/<ID>: always present

• topics is a dict:

  key	type	description
  page	int	page number
  page_size	int	number of topics per page
  start	int	initial # of topic in current page
  total	int	total number of topics
  items	list	list of topic

• topic is a dict, having at least 3 mandatory elements:

  key	type	opt	description
  key	str		String to be used as KVP value in the query
  label	str		Label (may be localized)
  is_localized	str	yes	If exists and it's true, tells that the label is already translated and requires no further localization actions by the client
  count	int	yes	Count of facet's item in current filter. May not exists in payloads for facets/<facet_name> with key queryparam specified for topics with 0 count.

The topics may also have other elements, according to the Facet handler; i.e.:

• categories may have a link to an icon,
• regions may have a bbox

e.g.:

"items": [
   {
      "key": "Pianificazione",
      "label": "Pianificazione",
      "is_localized": true,
      "count": 156,
      "fa_class": "fa-home"
   },

Filtering

The facets payloads provide all the info to create a filter on the resources. In order to create a filter on the topic you need to add in the KVP string FACET_FILTER=ITEM_KEY. For instance, if we have this payload:

{
   "name": "3-2-4-1-gemet-inspire-themes-rdf",
   "filter": "filter{tkeyword}",
   "label": "Categorie tematiche INSPIRE",
   "is_localized": true,
   ...
   "topics": {
      ...
      "items": [
         {
            "key": 36,
            "label": "Zone a rischio naturale",
            "is_localized": true,
            "count": 152
         },
    ...

in order to filter by "Zone a rischio naturale" we need to add in the search query filter{tkeyword}=36

Configuration

The faceting framework is extensible and configurable:

• faceting is implemented by extending a base class FacetProvider
• the list of facets can be configured in the setting:

   FACET_PROVIDERS = (
       "geonode.facets.providers.category.CategoryFacetProvider",
       "geonode.facets.providers.users.OwnerFacetProvider",
       "geonode.facets.providers.thesaurus.ThesaurusFacetProvider",
   )