> ## Documentation Index
> Fetch the complete documentation index at: https://docs.drain.lat/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Search

> Search Google Images and retrieve structured image results with metadata.

# Google Image Search

**Base URL:** `https://drain.lat/api/v1/imagesearch`

<Note>
  Powered by Google Custom Search API. Results are cached for 10 minutes per unique query to reduce API quota usage.
</Note>

<AccordionGroup>
  <Accordion title="GET /search" icon="magnifying-glass">
    Search Google Images and retrieve structured image results with metadata.

    ```
    GET /api/v1/imagesearch/search
    ```

    <ParamField query="q" type="string" required>
      Search query/keywords. Can also use `query` parameter.
    </ParamField>

    <ParamField query="num" type="number">
      Number of results to return. Range: `1-10`. Default `10`.
    </ParamField>

    <ParamField query="start" type="number">
      Starting index for pagination. Default `1`.
    </ParamField>

    <ParamField query="safe" type="string">
      Safe search level. Options: `off`, `active`. Default `off`.
    </ParamField>

    <ParamField query="imgSize" type="string">
      Image size filter. Options: `huge`, `icon`, `large`, `medium`, `small`, `xlarge`, `xxlarge`.
    </ParamField>

    <ParamField query="imgType" type="string">
      Image type filter. Options: `clipart`, `face`, `lineart`, `stock`, `photo`, `animated`.
    </ParamField>

    <ParamField query="imgColorType" type="string">
      Color type filter. Options: `color`, `gray`, `mono`, `trans`.
    </ParamField>

    <ParamField query="imgDominantColor" type="string">
      Dominant color filter. Options: `black`, `blue`, `brown`, `gray`, `green`, `orange`, `pink`, `purple`, `red`, `teal`, `white`, `yellow`.
    </ParamField>

    <ParamField query="fileType" type="string">
      File format filter. Options: `jpg`, `png`, `gif`, `bmp`, `svg`, `webp`, `ico`, `raw`.
    </ParamField>

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://drain.lat/api/v1/imagesearch/search?q=cats" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```bash cURL (with filters) theme={null}
      curl "https://drain.lat/api/v1/imagesearch/search?q=sunset&num=5&imgSize=large&imgDominantColor=orange" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch(
        "https://drain.lat/api/v1/imagesearch/search?q=cats&num=10",
        { headers: { "x-api-key": "YOUR_API_KEY" } }
      );
      const data = await res.json();
      ```

      ```javascript JavaScript (with filters) theme={null}
      const params = new URLSearchParams({
        q: "logo",
        imgType: "clipart",
        fileType: "png",
        num: 5
      });

      const res = await fetch(
        `https://drain.lat/api/v1/imagesearch/search?${params}`,
        { headers: { "x-api-key": "YOUR_API_KEY" } }
      );
      const data = await res.json();
      ```

      ```python Python theme={null}
      import requests

      res = requests.get(
          "https://drain.lat/api/v1/imagesearch/search",
          params={"q": "cats", "num": 10},
          headers={"x-api-key": "YOUR_API_KEY"}
      )
      print(res.json())
      ```

      ```python Python (with filters) theme={null}
      import requests

      params = {
          "q": "nature",
          "imgDominantColor": "green",
          "safe": "medium",
          "imgSize": "large",
          "num": 5
      }

      res = requests.get(
          "https://drain.lat/api/v1/imagesearch/search",
          params=params,
          headers={"x-api-key": "YOUR_API_KEY"}
      )
      print(res.json())
      ```
    </CodeGroup>

    <ResponseField name="query" type="string">The search query used.</ResponseField>

    <ResponseField name="images" type="array">
      <Expandable title="image object">
        <ResponseField name="title" type="string">Image title/alt text.</ResponseField>
        <ResponseField name="link" type="string">Direct URL to the full-size image.</ResponseField>
        <ResponseField name="displayLink" type="string">Domain name of the image host.</ResponseField>
        <ResponseField name="snippet" type="string">Description or context of the image.</ResponseField>
        <ResponseField name="thumbnailUrl" type="string">URL to thumbnail version.</ResponseField>
        <ResponseField name="thumbnailWidth" type="number">Thumbnail width in pixels.</ResponseField>
        <ResponseField name="thumbnailHeight" type="number">Thumbnail height in pixels.</ResponseField>
        <ResponseField name="imageUrl" type="string">Direct URL to full image (same as link).</ResponseField>
        <ResponseField name="imageWidth" type="number">Full image width in pixels.</ResponseField>
        <ResponseField name="imageHeight" type="number">Full image height in pixels.</ResponseField>
        <ResponseField name="contextLink" type="string">URL of the page containing the image.</ResponseField>
        <ResponseField name="fileFormat" type="string">MIME type (e.g. `image/jpeg`, `image/png`).</ResponseField>
        <ResponseField name="byteSize" type="number">File size in bytes.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total" type="number">Number of results returned in this response.</ResponseField>
    <ResponseField name="totalResults" type="number">Estimated total results available.</ResponseField>
    <ResponseField name="searchTime" type="number">Search execution time in seconds.</ResponseField>
    <ResponseField name="nextPage" type="number">Starting index for next page of results. `null` if no more pages.</ResponseField>

    ```json Response theme={null}
    {
      "query": "cats",
      "images": [
        {
          "title": "Cute cat sitting on windowsill",
          "link": "https://example.com/images/cat.jpg",
          "displayLink": "example.com",
          "snippet": "A beautiful orange cat enjoying the sunshine",
          "thumbnailUrl": "https://encrypted-tbn0.gstatic.com/images?q=...",
          "thumbnailWidth": 150,
          "thumbnailHeight": 150,
          "imageUrl": "https://example.com/images/cat.jpg",
          "imageWidth": 1920,
          "imageHeight": 1080,
          "contextLink": "https://example.com/cats-page",
          "fileFormat": "image/jpeg",
          "byteSize": 245678
        },
        {
          "title": "Black and white cat portrait",
          "link": "https://another-site.com/cat2.png",
          "displayLink": "another-site.com",
          "snippet": "Professional cat photography",
          "thumbnailUrl": "https://encrypted-tbn0.gstatic.com/images?q=...",
          "thumbnailWidth": 150,
          "thumbnailHeight": 100,
          "imageUrl": "https://another-site.com/cat2.png",
          "imageWidth": 2560,
          "imageHeight": 1440,
          "contextLink": "https://another-site.com/gallery",
          "fileFormat": "image/png",
          "byteSize": 512000
        }
      ],
      "total": 10,
      "totalResults": 1500000,
      "searchTime": 0.28,
      "nextPage": 11,
      "scrapedAt": "2026-05-31T10:30:00.000Z"
    }
    ```

    ## Pagination

    To get the next page of results, use the `nextPage` value from the response as the `start` parameter:

    ```bash theme={null}
    # First page
    GET /api/v1/imagesearch/search?q=cats

    # Second page
    GET /api/v1/imagesearch/search?q=cats&start=11

    # Third page
    GET /api/v1/imagesearch/search?q=cats&start=21
    ```

    ## Filter Examples

    ```bash theme={null}
    # Large sunset images
    GET /api/v1/imagesearch/search?q=sunset&imgSize=large

    # PNG clipart logos
    GET /api/v1/imagesearch/search?q=logo&imgType=clipart&fileType=png

    # Green nature photos
    GET /api/v1/imagesearch/search?q=nature&imgDominantColor=green&imgType=photo

    # Safe search for faces
    GET /api/v1/imagesearch/search?q=people&imgType=face&safe=high

    # Black and white photos
    GET /api/v1/imagesearch/search?q=vintage&imgColorType=gray
    ```

    <Warning>
      Uses Google Custom Search API quota (100 queries per day on free tier). Returns `429` error when quota is exceeded. Results are cached for 10 minutes to reduce quota usage.
    </Warning>
  </Accordion>
</AccordionGroup>