Text Search

Semantic Search

This semantic search route allows text search against our entire database of foods, products, and recipes.

Simply URL Encode your search term to take care of special characters, and send the request! The default limit (max results returned) is 50. This is the recommended setting, but can be adjusted as needed.

Optional Headers

Both search endpoints support Passio-Product-Localization (translate results) and Passio-Search-Config (filter by region, source, type, concern flags). See the Localization page for full details, supported values, and SDK equivalents.

Semantic Food Search (AI-powered) — Recommended

get

The recommended search endpoint for user-typed queries. AI-powered search that interprets the user's intent — handles synonyms, dietary intent ("vegan pizza"), category-style queries ("breakfast smoothie"), and natural-language phrasing — and returns a comprehensive Passio food set.

Use this when

A human is typing into a search bar and you want forgiving, intuitive results.
You want one call to expand a term into related items (replaces the legacy generateSearchTerms
- manual fan-out flow).

Use /napi/food/search/advanced instead when you need fast, exact-match search across brand / product names without AI expansion.

Filtering & localization

Supports the Passio-Search-Config, Passio-Product-Localization, and Localization-ISO headers — see the per-parameter docs for how to filter by region, data source, item type, etc.

Input / output

Query: term (required), limit (optional).
Headers: see search config / localization headers.
Response: OutgoingSearchResults.

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /v2/token-cache/unified/oauth/token/{YourAPIKey}

Query parameters

termstringRequired

Enter your search term here.

limitintegerOptional

Maximum number of results to return.

Default: 50

Header parameters

Passio-Search-ConfigstringOptional

Search Configuration. JSON-encoded object that controls data sources, result limits, and filtering. If omitted, server defaults are used (100 Passio results, 10 Edamam ingredients, 0 Edamam recipes, no filters).

See the PassioSearchConfigurationHeader schema for the full JSON structure.

Fields:

dataSourceConfigs — Array of {name, requestResultCount} controlling which external data sources are queried. Set requestResultCount to 0 to disable a source. Valid names: passio (default 100, max 1000), edamam_ingredients (default 10, max 50), edamam_recipes (default 0, max 25).
regionFilters — Map of region codes to priority weights (1=highest, 10=lowest). Accepts BCP 47 codes (en-US), ISO country codes (AU), or language codes (ja). Only foods matching these regions are returned.
typeFilters — Array of allowed item types: generic, branded, recipe.
sourceFilters — Array filtering within the Passio data source by origin sub-source. Valid values: fdc, firebase, legacy, openfood, passio, Passio addition, passio-foodai. Does not affect Edamam results.
ignoreWithConcernFlags — Array of integer concern flag IDs. Results with matching flags are removed.
strictRegionMode — Boolean. true removes items without country data when region filters are active; false keeps them.

Note: When any filter (region, type, or source) is active, result caching is skipped to ensure filters are always applied to fresh data.

Example: {"regionFilters":{"AU":1},"typeFilters":["branded","generic"]}

Passio-Product-LocalizationstringOptional

Regional Context & Routing. BCP 47 language-region tag (e.g. en-AU, ja-JP) or language code (e.g. ja) indicating the user's locale.

This header has three effects:

Regional search routing — Routes to a region-specific search index if one exists, with automatic fallback to the global index.
AI regional context — Injects regional context into Nutrition Advisor prompts for culturally accurate food identification.
Cache differentiation — Region-specific results are cached separately.

This is different from Localization-ISO: this header changes which results are returned (regional data), while Localization-ISO changes the language of the response text.

Example: en-AU

Responses

200

Successful response

application/json

alternateNamesstring[]Optional

400

Bad Request - Invalid input.

application/json

500

Internal Server Error.

application/json

get

/napi/food/search/semantic

GET /v2/products/napi/food/search/semantic?term=text HTTP/1.1
Host: api.passiolife.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "type": "text",
      "displayName": "text",
      "shortName": "text",
      "longName": "text",
      "scoredName": "text",
      "score": 1,
      "brandName": "text",
      "iconId": "text",
      "labelId": "text",
      "synonymId": "text",
      "recipeId": "text",
      "referenceId": "text",
      "resultId": "text",
      "nutritionPreview": {
        "portion": {
          "quantity": 1,
          "weight": {
            "unit": "text",
            "value": 1
          },
          "name": "text",
          "suggestedQuantity": [
            1
          ]
        },
        "calories": 1,
        "carbs": 1,
        "fat": 1,
        "protein": 1,
        "fiber": 1
      },
      "refCode": "text",
      "tags": [
        "text"
      ],
      "concerns": [
        1
      ],
      "itemType": "text",
      "productCode": "text"
    }
  ],
  "alternateNames": [
    "text"
  ]
}

Search Foods (Legacy)

This route allows text search against our entire database of foods, products, and recipes.

Advanced Food Search (text matching, no AI expansion)

get

Direct text search across product names, synonyms, recipes, and reference foods. Doesn't use AI to expand the term — so it's faster and more deterministic than semantic search, and tends to win for exact brand or product lookups (UPC labels typed by hand, branded products, specific SKUs).

Use this when

The user typed a brand name or exact product they want to find.
You're powering an autocomplete that needs sub-100 ms latency.
You want broad-but-literal matching across all Passio name fields.

For fuzzy / intent-based queries, prefer /napi/food/search/semantic.

Filtering & localization

Supports the Passio-Search-Config, Passio-Product-Localization, and Localization-ISO headers.

Input / output

Query: term (required), limit, alternatesOnly.
Response: OutgoingSearchResults.

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /v2/token-cache/unified/oauth/token/{YourAPIKey}

Query parameters

termstringRequired

The text to search for.

limitintegerOptional

Maximum number of results to return.

Default: 50

alternatesOnlybooleanOptional

When true, returns only alternative search suggestions.

Default: false

Header parameters

Passio-Search-ConfigstringOptional

See the PassioSearchConfigurationHeader schema for the full JSON structure.

Fields:

dataSourceConfigs — Array of {name, requestResultCount} controlling which external data sources are queried. Set requestResultCount to 0 to disable a source. Valid names: passio (default 100, max 1000), edamam_ingredients (default 10, max 50), edamam_recipes (default 0, max 25).
regionFilters — Map of region codes to priority weights (1=highest, 10=lowest). Accepts BCP 47 codes (en-US), ISO country codes (AU), or language codes (ja). Only foods matching these regions are returned.
typeFilters — Array of allowed item types: generic, branded, recipe.
sourceFilters — Array filtering within the Passio data source by origin sub-source. Valid values: fdc, firebase, legacy, openfood, passio, Passio addition, passio-foodai. Does not affect Edamam results.
ignoreWithConcernFlags — Array of integer concern flag IDs. Results with matching flags are removed.
strictRegionMode — Boolean. true removes items without country data when region filters are active; false keeps them.

Note: When any filter (region, type, or source) is active, result caching is skipped to ensure filters are always applied to fresh data.

Example: {"regionFilters":{"AU":1},"typeFilters":["branded","generic"]}

Passio-Product-LocalizationstringOptional

Regional Context & Routing. BCP 47 language-region tag (e.g. en-AU, ja-JP) or language code (e.g. ja) indicating the user's locale.

This header has three effects:

Regional search routing — Routes to a region-specific search index if one exists, with automatic fallback to the global index.
AI regional context — Injects regional context into Nutrition Advisor prompts for culturally accurate food identification.
Cache differentiation — Region-specific results are cached separately.

This is different from Localization-ISO: this header changes which results are returned (regional data), while Localization-ISO changes the language of the response text.

Example: en-AU

Responses

200

Successful response

application/json

alternateNamesstring[]Optional

400

Bad Request - Invalid input.

application/json

500

Internal Server Error.

application/json

get

/napi/food/search/advanced

GET /v2/products/napi/food/search/advanced?term=text HTTP/1.1
Host: api.passiolife.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "type": "text",
      "displayName": "text",
      "shortName": "text",
      "longName": "text",
      "scoredName": "text",
      "score": 1,
      "brandName": "text",
      "iconId": "text",
      "labelId": "text",
      "synonymId": "text",
      "recipeId": "text",
      "referenceId": "text",
      "resultId": "text",
      "nutritionPreview": {
        "portion": {
          "quantity": 1,
          "weight": {
            "unit": "text",
            "value": 1
          },
          "name": "text",
          "suggestedQuantity": [
            1
          ]
        },
        "calories": 1,
        "carbs": 1,
        "fat": 1,
        "protein": 1,
        "fiber": 1
      },
      "refCode": "text",
      "tags": [
        "text"
      ],
      "concerns": [
        1
      ],
      "itemType": "text",
      "productCode": "text"
    }
  ],
  "alternateNames": [
    "text"
  ]
}

PreviousFood Details NextImage Recognition

Last updated 3 months ago