Feature Request: Support searching by brand + product name together

[rbo-corematic]

Hello Brocade.io team,

First, thank you for providing an open and accessible product database!

I have a feature request regarding the /api/items search endpoint. Currently, it appears that searching by product name and by brand are both supported individually (e.g., ?query=cluedo or ?query=hasbro). However, there is no way to directly search for items that match both a specific brand and a specific product name in a single query (e.g., "Hasbro Cluedo" should only return Cluedo products from Hasbro, not all Hasbro or all Cluedo products).

Use Case:

• Users often want to find a product by both its brand and its name, especially for common product names that exist across multiple brands.
• At the moment, the only workaround is to search by product name and then filter the results client-side by brand, which is less efficient and may not scale well for large result sets.

Feature Request:
Add support for searching by both brand and product name together, either by:

• Accepting separate brand and name query parameters (e.g., /api/items?brand=Hasbro&name=Cluedo)
• Or improving the query logic so that ?query=Hasbro+Cluedo returns only items where both the brand and product name match.

Benefits:

• More precise search results for end users and developers.
• Reduces the need for client-side filtering and extra API calls.

Is this something that could be considered for a future update? Thank you for your time and for maintaining this valuable resource!

Best regards,
Renaud

[ferrisoxide]

TL;DR

"Accepting separate brand and name query parameters" makes sense. We will look to implementing that post haste.

---

Hi Renaud

Thanks for the feedback.

Great timing btw. We're currently working (as in, this week) on an overhaul for the search mechanism. We've made some major changes to the way JSON data is stored (#113) and are aiming to make querying more precise based on those changes. We're also looking to fix some bugs (#126).

The underlying data for products will ultimately look something like the JSON payloads below. We've actually already transformed the data - we just need to make some UX changes and QA before swapping over to the new data.

The query format that you're suggesting would require a mapping of 'name' to 'productName' (and a slightly more complicated interrogation of the gs1:brand key/value set), but having sensible aliases for these keys is fine.

We want to allow searches on explicit fields. For example, in the case of a book like the example below, we'd want enable searches like ?author=John%20Maeda or ?publisher=The%20MIT%20Press.

A few things I still haven't figured out yet:

• how to represent partial matches
• logical or'ing (and'ing is assumed to be the default)

Some upcoming changes you probably need to know about:

• the JSON payload returned via the API is going to change, from the current ad hoc structure to one based on the GS1 Web Vocabulary per the examples below
• unitCode attributes will be expressed using CEFACT codes
• we may retire the api/items/ endpoint in favour of api/products, just to make things line up with the HTML endpoint - but if we do we'll provide an alias for the interim.
• we are looking to expand the number of products in the database by an order of magnitude

For now, we'll look to getting the basic ?brand=Hasbro&name=Cluedo style search working first and then start thinking through some of the more complicated use cases. I'm considering whether we should do partial match by default - e.g. the query param "Cluedo" would match for the name "Cluedo standard" - but if you have any thoughts here we'd be keen to hear them.

Again, thanks for the feature request. Feel free to make more requests, or contact us directly, if you want to talk more about what you need from the brocade.io service.

Cheers,
Tom

---

Example Product

{
  "@type": "gs1:Product",
  "@context": {
    "gs1": "https://gs1.org/voc/"
  },
  "gs1:gtin": "5010994642389",
  "gs1:brand": {
    "@type": "gs1:Organization",
    "gs1:name": "Hasbro"
  },
  "gs1:netContent": {
    "gs1:value": 1,
    "gs1:unitCode": "C62"
  },
  "gs1:productName": "Cluedo standard"
}

Example Book

{
  "@type": "schema:Book",
  "@context": {
    "gs1": "https://gs1.org/voc/",
    "schema": "https://schema.org/"
  },
  "gs1:gtin": "09780262134729",
  "schema:author": "John Maeda",
  "gs1:productName": "The Laws Of Simplicity",
  "schema:publisher": "The MIT Press",
  "schema:numberOfPages": 100
}

[ferrisoxide]

@rbo-corematic

Changes are up on the production server. Visiting

https://www.brocade.io/api/items?brand=Hasbro&name=Cluedo

returns

[
  {
    "gtin14": "5010994642389",
    "brand_name": "Hasbro",
    "name": "Cluedo standard",
    "unit_count": 1
  },
  {
    "gtin14": "0653569343547",
    "brand_name": "Hasbro",
    "name": "Cluedo Harry Potter",
    "unit_count": 1
  }
]

Let me know if this is satisfactory.

NB We haven't swapped over to the new JSON-LD model yet as I was concerned it might impact any client code you already have. If we had it switched over, the payload would have looked like this:

[
  {
    "@type": "gs1:Product",
    "@context": {
      "gs1": "https://gs1.org/voc/"
    },
    "gs1:gtin": "5010994642389",
    "gs1:brand": {
      "@type": "gs1:Organization",
      "gs1:name": "Hasbro"
    },
    "gs1:netContent": {
      "gs1:value": 1,
      "gs1:unitCode": "C62"
    },
    "gs1:productName": "Cluedo standard"
  },
  {
    "@type": "gs1:Product",
    "@context": {
      "gs1": "https://gs1.org/voc/"
    },
    "gs1:gtin": "0653569343547",
    "gs1:brand": {
      "@type": "gs1:Organization",
      "gs1:name": "Hasbro"
    },
    "gs1:netContent": {
      "gs1:value": 1,
      "gs1:unitCode": "C62"
    },
    "gs1:productName": "Cluedo Harry Potter"
  }
]

Eventually I do want to swap to this model, but I'll make it switchable if it's going to cause issues.

[ferrisoxide]

@rbo-corematic

I'll leave the /api/items endpoint as it is now. There's now a new /api/prooducts endpoint that will serve up product data in JSON-LD format. See:

https://www.brocade.io/api/products?brand=Hasbro&name=Cluedo