Google images API

Search Google Images and get each full-size image with the page it comes from

curl --request POST \
  --url https://api.stophy.dev/v1/google/images \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "golden retriever puppy"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: 'golden retriever puppy'})
};

fetch('https://api.stophy.dev/v1/google/images', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.stophy.dev/v1/google/images"

payload = { "query": "golden retriever puppy" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "data": {
    "results": [
      {
        "imageUrl": "<string>",
        "pageUrl": "<string>",
        "width": 0,
        "height": 0,
        "thumbnailUrl": "<string>",
        "position": 0,
        "title": "<string>",
        "source": "<string>"
      }
    ]
  },
  "creditsUsed": 123,
  "requestId": "<string>"
}

{
  "success": false,
  "error": {
    "code": "cliSessionCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123,
    "requiredCredits": 123,
    "availableCredits": 123,
    "billingUrl": "https://stophy.dev/billing"
  }
}

{
  "success": false,
  "error": {
    "code": "cliSessionCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123,
    "requiredCredits": 123,
    "availableCredits": 123,
    "billingUrl": "https://stophy.dev/billing"
  }
}

POST

google

images

Search Google Images and get each full-size image with the page it comes from

curl --request POST \
  --url https://api.stophy.dev/v1/google/images \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "golden retriever puppy"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: 'golden retriever puppy'})
};

fetch('https://api.stophy.dev/v1/google/images', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.stophy.dev/v1/google/images"

payload = { "query": "golden retriever puppy" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "data": {
    "results": [
      {
        "imageUrl": "<string>",
        "pageUrl": "<string>",
        "width": 0,
        "height": 0,
        "thumbnailUrl": "<string>",
        "position": 0,
        "title": "<string>",
        "source": "<string>"
      }
    ]
  },
  "creditsUsed": 123,
  "requestId": "<string>"
}

{
  "success": false,
  "error": {
    "code": "cliSessionCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123,
    "requiredCredits": 123,
    "availableCredits": 123,
    "billingUrl": "https://stophy.dev/billing"
  }
}

{
  "success": false,
  "error": {
    "code": "cliSessionCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123,
    "requiredCredits": 123,
    "availableCredits": 123,
    "billingUrl": "https://stophy.dev/billing"
  }
}

Searches Google Images and returns each full-size image with the page it comes from.

Request

query is required.

import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.images({ query: "golden retriever puppy" });
console.log(result.data.results);

from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.images(query="golden retriever puppy")
print(result["data"]["results"])

curl -X POST https://api.stophy.dev/v1/google/images \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"golden retriever puppy"}'

stophy google images "golden retriever puppy"

Response

If successful, the response body contains the standard envelope. data.results[] contains the images, each with its full-size link and the page it comes from. The following example is illustrative.

{
  "success": true,
  "data": {
    "results": [
      {
        "imageUrl": "https://images.example.com/golden-retriever-puppy.jpg",
        "title": "Golden retriever puppy in the grass",
        "pageUrl": "https://www.example.com/dog-breeds/golden-retriever",
        "source": "example.com",
        "width": 1600,
        "height": 1067,
        "thumbnailUrl": "https://images.example.com/thumbs/golden-retriever-puppy.jpg",
        "position": 1
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}

Field	Type	Description
`position`	integer	The 1-based position of the result in the list.

For every field, see the response schema on this page.

Optional parameters

Parameter	Type	Description
`country`	string	The country to query, as a two-letter ISO 3166-1 code such as `us`.
`language`	string	The language of the results, as a two-letter ISO 639-1 code such as `en`.
`size`	string	Restricts results to images of this size. Acceptable values are `large`, `medium` and `icon`.
`color`	string	Restricts results to images in this color. Accepts one of 14 values, such as `blackAndWhite`, `transparent` and `red`.
`type`	string	The kind of image. Acceptable values are `clipArt`, `lineDrawing` and `gif`.
`time`	string	Restricts results to images from this period. Acceptable values are `past24Hours`, `pastWeek`, `pastMonth` and `pastYear`.
`usageRights`	string	Restricts results to images with this license. Acceptable values are `creativeCommons` and `commercial`.
`limit`	integer	The maximum number of images to return. Billed at 1 credit per 10 returned. Must be between 1 and 100.

Billing

A successful request consumes 1 credit per 10 images, up to 10 credits. Requests that fail, or that return no items, are not billed. Set limit to cap the number of items returned and billed.

Pagination

This method is not paginated. A single request returns the complete result.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

query

string

required

Required string length: 1 - 400

country

string

ISO 3166-1 alpha-2 country code, e.g. us. Any case is accepted.

Pattern: ^[A-Za-z]{2}$

language

string

Two-letter language code like en or pt. Any case is accepted.

Pattern: ^[A-Za-z]{2}$

size

enum<string>

Available options:

large,

medium,

icon

color

enum<string>

Available options:

blackAndWhite,

transparent,

red,

orange,

yellow,

green,

teal,

blue,

purple,

pink,

white,

gray,

black,

brown

type

enum<string>

Available options:

clipArt,

lineDrawing,

gif

time

enum<string>

Available options:

past24Hours,

pastWeek,

pastMonth,

pastYear

usageRights

enum<string>

Creative Commons, or commercial and other licenses.

Available options:

creativeCommons,

commercial

limit

integer

Return at most this many images. You pay 1 credit per 10 returned.

Required range: 1 <= x <= 100

Response

The data, and the credits this call used.

success

any

required

data

object

required

Show child attributes

creditsUsed

integer

required

requestId

string

required

Using the API

Catalog

Account

Search and AI answers

Video

Social

Places and travel

Jobs

Shopping

Apps

Real estate

Ads

Google images API

Request

Response

Optional parameters

Billing

Authorizations

Body

Response

​Request

​Response

​Optional parameters

​Billing

​Pagination

Authorizations

Body

Response

Request

Response

Optional parameters

Billing

Pagination