Line 14: |
Line 14: |
| Products from the chocolate category, with both the organic label and the fair trade label: | | Products from the chocolate category, with both the organic label and the fair trade label: |
| | | |
− | * V1: | + | * V1: |
− | * V2: https://world.openfoodfacts.org/api/v2/search?categories_tags_en=chocolates&labels_tags_en=organic,fair%20trade&fields=code,product_name | + | ** https://world.openfoodfacts.org/cgi/search.pl?action=process&tagtype_0=categories&tag_contains_0=contains&tag_0=chocolates&tagtype_1=labels&tag_contains_1=contains&tag_1=organic&tagtype_2=labels&tag_contains_2=contains&tag_2=fair-trade&json=1 (cannot select the fields returned) |
| + | * V2 |
| + | ** https://world.openfoodfacts.org/api/v2/search?categories_tags_en=chocolates&labels_tags_en=organic,fair%20trade&fields=code,product_name (returns only selected fields) |
| + | ** https://world.openfoodfacts.org/search?categories_tags_en=chocolates&labels_tags_en=organic,fair%20trade (corresponding Web site endpoint) |
| | | |
| == Features == | | == Features == |
Line 27: |
Line 30: |
| * /search will replace /cgi/search.pl as the url of search results | | * /search will replace /cgi/search.pl as the url of search results |
| * /api/v2/search will return JSON results, with the exact same parameters as the /search endpoint | | * /api/v2/search will return JSON results, with the exact same parameters as the /search endpoint |
| + | |
| + | === Selection of the fields returned === |
| + | |
| + | It is possible to specify which fields are returned for each result: |
| + | |
| + | * [https://world.openfoodfacts.org/api/v2/search?categories_tags=en:meals&fields=code,product_name,brands,attribute_groups fields=code,product_name,brands,attribute_groups] |
| | | |
| === Simplified parameters specification === | | === Simplified parameters specification === |
| | | |
| Tags fields are now specified directly: | | Tags fields are now specified directly: |
− | * labels_tags=en:organic | + | * [https://world.openfoodfacts.org/api/v2/search?labels_tags=en:organic&fields=code,product_name,labels_tags labels_tags=en:organic] |
− | * labels_tags_fr=bio -> bio is assumed to be in French and thus converted to en:organic | + | * [https://world.openfoodfacts.org/api/v2/search?labels_tags_fr=bio&fields=code,product_name,labels_tags_en labels_tags_fr=bio] -> bio is assumed to be in French and thus converted to en:organic |
| | | |
| For AND queries, use comma separated values: | | For AND queries, use comma separated values: |
| | | |
− | * labels_tags=en:organic,en:fair-trade | + | * [https://world.openfoodfacts.org/api/v2/search?labels_tags=en:organic,en:fair-trade&fields=code,product_name,labels_tags labels_tags=en:organic,en:fair-trade] |
| | | |
| For negative queries, prefix tag with - | | For negative queries, prefix tag with - |
− | * labels_tags=-en:organic,-en:fair-trade | + | * [https://world.openfoodfacts.org/api/v2/search?labels_tags=en:organic,-en:fair-trade&fields=code,product_name,labels_tags labels_tags=-en:organic,-en:fair-trade] |
| | | |
| === OR tags fields queries === | | === OR tags fields queries === |
| | | |
| For OR queries, use | to separate values | | For OR queries, use | to separate values |
− | * labels_tags=en:organic|en:fair-trade|en:some-other-label | + | * [https://world.openfoodfacts.org/api/v2/search?labels_tags=en:organic|en:fair-trade|en:some-other-label&fields=code,product_name,labels_tags labels_tags=en:organic|en:fair-trade|en:some-other-label] |
| | | |
| === Conditions on nutrients === | | === Conditions on nutrients === |
| | | |
| * Per 100g or per serving | | * Per 100g or per serving |
− | ** energy-kj_100g < 200 | + | ** [https://world.openfoodfacts.org/api/v2/search?categories_tags=en:sodas&energy-kj_100g%3C200&fields=code,product_name,energy-kj_100g energy-kj_100g<200] |
− | ** sugars_serving > 10 | + | ** [https://world.openfoodfacts.org/api/v2/search?categories_tags=en:sodas&sugars_serving%3E10g&fields=code,product_name,sugars_serving sugars_serving>10] |
| * Per the product as sold, or prepared | | * Per the product as sold, or prepared |
− | ** saturated-fat_100g (as sold) | + | ** [https://world.openfoodfacts.org/api/v2/search?categories_tags=en:sodas&saturated-fat_100g=1&fields=code,product_name,saturated-fat_100g saturated-fat_100g=1] (as sold) |
− | ** salt_prepared_serving (prepared, per serving) | + | ** [https://world.openfoodfacts.org/api/v2/search?categories_tags=en:meals&salt_prepared_serving=1&fields=code,product_name,salt_prepared_serving salt_prepared_serving] (prepared, per serving) |
| | | |
| == Development and deployment == | | == Development and deployment == |
| | | |
− | The new Search API V2 has been be developed and deployed incrementally, and it co-exists with the existing Search API V1. | + | The new Search API V2 has been developed and deployed incrementally in August and September 2020. The new V2 API co-exists with the existing Search API V1. |
| | | |
| V1 of the API will be supported for the years to come as many apps are using it. | | V1 of the API will be supported for the years to come as many apps are using it. |
| | | |
− | === Tags fields === | + | === Related issues === |
| | | |
| * [https://github.com/openfoodfacts/openfoodfacts-server/issues/4011 New search API - tags fields #4011] - done | | * [https://github.com/openfoodfacts/openfoodfacts-server/issues/4011 New search API - tags fields #4011] - done |
| + | * [https://github.com/openfoodfacts/openfoodfacts-server/issues/4075 New search API - conditions on nutrients #4075] - done |
| | | |
− | === Nutrients === | + | === Related PRs === |
| | | |
− | * [https://github.com/openfoodfacts/openfoodfacts-server/issues/4075 New search API - conditions on nutrients #4075] - done | + | * [https://github.com/openfoodfacts/openfoodfacts-server/pull/4039 New search API + simplified parameter handling] |
| + | * [https://github.com/openfoodfacts/openfoodfacts-server/pull/4127 Support conditions on nutrients for new search API] |
| + | * [https://github.com/openfoodfacts/openfoodfacts-server/pull/4129 Return only specific nutrients through the API] |
| + | * [https://github.com/openfoodfacts/openfoodfacts-server/pull/4133 New Search API features + New Product Attributes] |
| + | * [https://github.com/openfoodfacts/openfoodfacts-server/pull/4240 New /search endpoint] |
| + | |
| + | == See also == |
| | | |
| + | [[Open Food Facts API Version 2]] |
| | | |
| [[Category:Project:Personalized_Search]] | | [[Category:Project:Personalized_Search]] |
| [[Category:ProductOpener]] | | [[Category:ProductOpener]] |
| + | [[Category:API]] |
| + | [[Category:Search]] |