search-a-licious API (0.1.0)

Download OpenAPI specification:Download

The Open Food Facts team: contact@openfoodfacts.org URL: https://world.openfoodfacts.org/ License: AGPL-3.0

The Search-a-licious API helps you quickly build applications with search capabilities.

You can find the API documentation here.

See also the available web-components to build your search interface.

See the project for more information.

Get Document

Fetch a document from Elasticsearch with specific ID.

path Parameters

identifier

required

string (Identifier)

query Parameters

Index Id (string) or Index Id (null) (Index Id)

Index ID to use for the search, if not provided, the default index is used. If there is only one index, this parameter is not needed.

Responses

Response samples

Content type

application/json

null

Search

This is the main search endpoint.

It uses POST request to ensure privacy.

Under the hood, it calls the :py:func:app.search.search function

Request Body schema: application/json

	Array of Facets (strings) or Facets (null) (Facets) Name of facets to return in the response as a comma-separated value. If None (default) no facets are returned.
	(Array of Charts (DistributionChart (object) or ScatterChart (object))) or Charts (null) (Charts) Name of vega representations to return in the response. Can be distribution chart or scatter plot. If you pass a simple string, it will be interpreted as a distribution chart, or a scatter plot if it is two fields separated by a column (x_axis_field:y_axis_field).
	Array of Fields (strings) or Fields (null) (Fields) List of fields to include in the response. All other fields will be ignored.
page_size	integer (Page Size) Default: 10 Number of results to return per page.
page	integer (Page) Default: 1 Number of results to return per page.
	Sort By (string) or Sort By (null) (Sort By) Field name to use to sort results, the field should exist and be sortable. If it is not provided, results are sorted by descending relevance score. (aka best match) If you put a minus before the name, the results will be sorted by descending order. If the field name match a known script (defined in your configuration), it will be use for sorting. In this case you also need to provide additional parameters corresponding to your script parameters. If a script needs parameters, you can only use the POST method. Beware that this may have a big impact on performance Also bare in mind privacy considerations if your script parameters contains sensible data.
	Q (string) or Q (null) (Q) The search query, it supports Lucene search query syntax (https://lucene.apache.org/core/3_6_0/queryparsersyntax.html). Words that are not recognized by the lucene query parser are searched as full text search. Example: `categories_tags:"en:beverages" strawberry brands:"casino"` query use a filter clause for categories and brands and look for "strawberry" in multiple fields. The query is optional, but `sort_by` value must then be provided.
boost_phrase	boolean (Boost Phrase) Default: false This enables an heuristic that will favor, matching terms that are consecutive. Technically, if you have a query with the two words `whole milk` it will boost entries with `"whole milk"` exact match. The boost factor is defined by `match_phrase_boost` value in Configuration Note, that it only make sense if you use best match sorting. So in any other case it is ignored.
langs	Array of strings (Langs) Default: ["en"] List of languages we want to support during search. This list should include the user expected language, and additional languages (such as english for example). This is currently used for language-specific subfields to choose in which subfields we're searching in. If not provided, `['en']` is used.
	Index Id (string) or Index Id (null) (Index Id) Index ID to use for the search, if not provided, the default index is used. If there is only one index, this parameter is not needed.
	Array of Debug Info (strings) or Debug Info (null) (Debug Info) Tells which debug information to return in the response. It can be a comma separated list of values
	Sort Params (object) or Sort Params (null) (Sort Params) Additional parameters when using a sort script in sort_by. If the sort script needs parameters, you can only be used the POST method.

Responses

Request samples

Payload

Content type

application/json

{"facets": ["string"
],
"charts": [{"chart_type": "DistributionChart",
"field": "string"
}
],
"fields": ["string"
],
"page_size": 10,
"page": 1,
"sort_by": "string",
"q": "string",
"boost_phrase": false,
"langs": ["en"
],
"index_id": "string",
"debug_info": ["aggregations"
],
"sort_params": { }
}

Response samples

Content type

application/json

null

Search Get

This is the main search endpoint when using GET request

Under the hood, it calls the :py:func:app.search.search function

query Parameters

	Array of Facets (strings) or Facets (null) (Facets) Name of facets to return in the response as a comma-separated value. If None (default) no facets are returned.
	(Array of Charts (DistributionChart (object) or ScatterChart (object))) or Charts (null) (Charts) Name of vega representations to return in the response. Can be distribution chart or scatter plot. If you pass a simple string, it will be interpreted as a distribution chart, or a scatter plot if it is two fields separated by a column (x_axis_field:y_axis_field).
	Array of Fields (strings) or Fields (null) (Fields) List of fields to include in the response. All other fields will be ignored.
page_size	integer (Page Size) Default: 10 Number of results to return per page.
page	integer (Page) Default: 1 Number of results to return per page.
	Sort By (string) or Sort By (null) (Sort By) Field name to use to sort results, the field should exist and be sortable. If it is not provided, results are sorted by descending relevance score. (aka best match) If you put a minus before the name, the results will be sorted by descending order. If the field name match a known script (defined in your configuration), it will be use for sorting. In this case you also need to provide additional parameters corresponding to your script parameters. If a script needs parameters, you can only use the POST method. Beware that this may have a big impact on performance Also bare in mind privacy considerations if your script parameters contains sensible data.
	Q (string) or Q (null) (Q) The search query, it supports Lucene search query syntax (https://lucene.apache.org/core/3_6_0/queryparsersyntax.html). Words that are not recognized by the lucene query parser are searched as full text search. Example: `categories_tags:"en:beverages" strawberry brands:"casino"` query use a filter clause for categories and brands and look for "strawberry" in multiple fields. The query is optional, but `sort_by` value must then be provided.
boost_phrase	boolean (Boost Phrase) Default: false This enables an heuristic that will favor, matching terms that are consecutive. Technically, if you have a query with the two words `whole milk` it will boost entries with `"whole milk"` exact match. The boost factor is defined by `match_phrase_boost` value in Configuration Note, that it only make sense if you use best match sorting. So in any other case it is ignored.
langs	Array of strings (Langs) Default: ["en"] List of languages we want to support during search. This list should include the user expected language, and additional languages (such as english for example). This is currently used for language-specific subfields to choose in which subfields we're searching in. If not provided, `['en']` is used.
	Index Id (string) or Index Id (null) (Index Id) Index ID to use for the search, if not provided, the default index is used. If there is only one index, this parameter is not needed.
	Array of Debug Info (strings) or Debug Info (null) (Debug Info) Tells which debug information to return in the response. It can be a comma separated list of values

Responses

Response samples

Content type

application/json

Example

ErrorSearchResponse

{"debug": {"lucene_query": "string",
"es_query": { },
"aggregations": { }
},
"errors": [{"title": "string",
"description": "string"
}
]
}

Taxonomy Autocomplete

API endpoint for autocompletion using taxonomies

query Parameters

q required	string (Q) User autocomplete query.
taxonomy_names required	string (Taxonomy Names) Name(s) of the taxonomy to search in, as a comma-separated value.
langs	string (Langs) Default: "en" Languages to search in (as a comma separated list), defaults to 'en'.
size	integer (Size) Default: 10 Number of results to return.
	Fuzziness (integer) or Fuzziness (null) (Fuzziness) Fuzziness level to use, default to no fuzziness.
	Index Id (string) or Index Id (null) (Index Id) Index ID to use for the search, if not provided, the default index is used. If there is only one index, this parameter is not needed.

Responses

Response samples

Content type

application/json

null

Off Demo

Redirects to the off.html page

Responses

Html Search

A demo page to test the search endpoint directly

query Parameters

	Q (string) or Q (null) (Q)
page	integer (Page) Default: 1
page_size	integer (Page Size) Default: 24
langs	string (Langs) Default: "fr,en"
	Sort By (string) or Sort By (null) (Sort By)
	Index Id (string) or Index Id (null) (Index Id) Index ID to use for the search, if not provided, the default index is used. If there is only one index, this parameter is not needed.
display_debug	boolean (Display Debug) Default: false

Responses

Response samples

Content type

application/json

{"detail": [{"loc": ["string"
],
"msg": "string",
"type": "string"
}
]
}

Robots Txt

Responses

Healthcheck

API endpoint to check the health of the application

It uses :py:mod:app.health.

Responses

Response samples

Content type

application/json

null