How to Search Images by Business Type and Page Section via API

A plain keyword search for "office" or "food" hands you a big, loosely sorted pile and leaves the real decision to you: which of these actually fits the about section of a consultant site, or the hero of a cafe homepage? This guide shows how to model that question as a structured query in an adapter you control, using Picdrome's human-facing taxonomy as the example.

This is a how-to companion to the broader walkthrough on adding website images automatically with an image API. Start there if you need the end-to-end picture; come here when you specifically want to filter by page section and business type.

Scope. This is a vendor-neutral search-model design, not documentation for a live Picdrome API. The parameter and response shapes are pseudocode for your own versioned adapter. The maintained developer hub explains the internal record and makes no endpoint or service claims.

Why "by use case" beats "by keyword"

Keyword search optimizes for subject. You type "coffee," you get pictures that contain coffee. But the thing you actually need is rarely "a picture of coffee" — it's "a wide, calm image for a cafe homepage hero with room for a headline and a button." Subject is one input; the slot the image has to fill is the other, and a keyword box can't express the slot.

Picdrome organizes its selection guidance around the slot, with guides to where an image goes on a page and by the kind of business it suits. Your own catalog adapter can normalize an approved source into those two filters, so a query like "about-page image for a consultant site" maps to a curated set instead of a keyword dragnet.

Two things make this work in code:

• A use case (page section) tells the API what job the image does — leave space for text, hold a banner shape, read fast at the top of an article.
• A business type tells the API what world the image should look like it belongs to — a quiet desk for a consultant, a bright plate for a cafe.

Filter on both and you've described "the right image for THIS section of THIS kind of site" without writing a single ambiguous keyword.

The two axes you can search

These are the two facets that matter most for placing an image. They line up one-to-one with the on-site collections, so you can see the same taxonomy whether you're browsing as a person or querying as a builder.

The use-case values are the same ones the single-image response already reports under suggested_use_cases — for example an image carrying "suggested_use_cases": ["homepage-hero", "about-section"] is exactly what a use_case=about-section filter selects for. That consistency is the point: the facet you filter on is the facet stamped on every result.

use_case and business_type are conceptual parameter names in this design example, not a stable production contract. The values themselves (homepage-hero, cafe, and so on) match the live collection slugs and the documented suggested_use_cases vocabulary.

Building a query: a hero image for a consultant site

Say you're filling the homepage hero on a consultant's site. In plain words: "a wide, overlay-friendly hero image that looks like it belongs to a consulting business." Translate that into the two facets — use_case=homepage-hero and business_type=consultant-coach — and send it as a search request.

GET /api/images/search?use_case=homepage-hero&business_type=consultant-coach&limit=10

Your adapter can combine the two filters and return slot-appropriate images, each carrying its metadata and license record inline:

{
  "query": {
    "use_case": "homepage-hero",
    "business_type": "consultant-coach"
  },
  "count": 2,
  "results": [
    {
      "name": "Calm consulting desk at a bright window",
      "slug": "calm-consulting-desk-window",
      "category": "workspaces",
      "tags": ["desk", "minimal", "overlay-friendly", "professional"],
      "alt_text": "Tidy desk with a notebook by a sunlit window",
      "suggested_use_cases": ["homepage-hero", "about-section"],
      "license": {
        "summary": "Read the current source license before publishing.",
        "attribution_required": null,
        "ai_generated": true,
        "terms_url": "/license"
      }
    },
    {
      "name": "Two people in a quiet advisory conversation",
      "slug": "advisory-conversation-quiet-room",
      "category": "people",
      "tags": ["conversation", "advisory", "calm", "overlay-friendly"],
      "alt_text": "Two people talking across a table in a calm office",
      "suggested_use_cases": ["homepage-hero", "service-page"],
      "license": {
        "summary": "Read the current source license before publishing.",
        "attribution_required": null,
        "ai_generated": true,
        "terms_url": "/license"
      }
    }
  ]
}

Notice what comes back with each image: suggested_use_cases confirming the slot fit, tags you can use to rank within the set (here, overlay-friendly flags images with calm space for a headline), and a license object you can act on in the same step.

Combining filters and reading the set

The two facets are meant to be combined with AND logic: use_case=homepage-hero&business_type=consultant-coach returns images that match both, not either. That's what narrows a broad gallery down to a usable shortlist.

When you read the returned set, lean on the metadata that's already there rather than re-querying:

• Use suggested_use_cases to confirm an image is built for your slot, not just compatible with it. An image listing homepage-hero first is a stronger hero candidate than one where it appears third.
• Use tags to rank within the set. For a hero, prefer overlay-friendly; for a blog header, prefer images tagged for a banner shape.
• Read alt_text straight into your markup so the placed image stays accessible.
• Read the license object on every image — never assume terms across results. More on why those fields matter in what image metadata matters when building pages programmatically.

Every normalized result should carry its source license record and AI-generated provenance. For Picdrome images, link to the current Picdrome Image License, do not infer an attribution rule, and block publishing if those terms do not clearly authorize the intended use. This is general information, not legal advice.

Mapping API results back to the collection pages

If your adapter deliberately maps its facets to the human collection slugs, you can move between the two views without another lookup table:

• A result from use_case=about-section lives in the on-site about-page collection under /use-cases/.
• A result from business_type=consultant-coach lives in the on-site consultant & coach collection under /business-types/.

This matters when you want a person to sanity-check what an agent pulled. Hand a teammate the collection URL that matches the query, and they see the same curated set your code searched — useful for AI website builders that let an end user swap a generated image for another from the same slot. For how that handoff works inside a builder, see how AI website builders pull in ready-to-use images.

Common query mistakes and how to fix them

A few patterns produce wrong-feeling results. Match the symptom to the fix.

Choose-this rule of thumb: if you know the page slot but not the industry, lead with use_case and leave business_type off until you need to narrow. If you know the industry but the slot is flexible, lead with business_type. Add the second facet only when the first returns too much. Adding both up front on a small library is the most common cause of an empty set — start broad, then tighten.

In Plain English

This is a design guide for mapping two Picdrome collection facets into a search interface: use_case (the page section, like homepage-hero or about-section, mirroring /use-cases/) and business_type (the industry, like consultant-coach or cafe, mirroring /business-types/). Combine them with AND logic to get a shortlist for "this section of this kind of site" instead of a keyword pile. The parameter names and response are pseudocode for your own adapter, not a Picdrome service contract. Preserve alt_text, suggested_use_cases, AI-generated provenance, and a link to the current Picdrome Image License, and block publishing when the intended use or attribution rule is unclear. See the maintained integration design guide and the pillar on adding website images automatically with an image API. This is general information, not legal advice.