imagesearch

README

imagesearch

A package designed to search Google Images based on the input query and arguments. These images may be protected under copyright, and you shouldn't do anything punishable with them, like using them for commercial use.

---

Arguments

There are 2 required parameters, along with a variety of different search arguments.

Argument	Type	Description
query:	string	The keyword(s) to search for.
limit	int	Cannot fetch more than 100.
arguments:	string	Optional search parameters are passed through here.

Search Arguments

These are used by passing imagesearch.{argument}.{option} in the arguments parameter. Only one option from each argument can be passed or Google will load the images without any arguments except the query.

Argument	Options	Description
Color	Red, Orange, Yellow, Green, Teal, Blue, Purple, Pink, White, Gray, Black, Brown	Filter images by the dominant color.
ColorType	Color, Grayscale, Transparent	Filter images by the color type, full color, grayscale, or transparent.
License	CreativeCommons, Other	Filter images by the usage license.
Type	Face, Photo, Clipart, Lineart, Animated	Filters by the type of images to search for. *Not to be confused with search_format*
Time	PastDay, PastWeek, PastMonth, PastYear	Only finds images posted in the time specified.
AspectRatio	Tall, Square, Wide, Panoramic	Specifies the aspect ratio of the images.
Format	Jpg, Gif, Png, Bmp, Svg, Webp, Ico, Raw	Filters out images that are not a specified format. If you would like to download images as a specific format, use the download_format argument instead.

---

Examples

This showcases the different functions provided and what each input and output means.

package main

import (
    "github.com/jibble330/imagesearch"
)

func main() {
    // Searches for "example", filtering by the color redand returns a slice of all the resulting urls.
    // imagesearch.Images works the same, instead returning Image types instead of string
    urls, err := imagesearch.Urls("example", 0, imagesearch.Color.Red) 
    if err != nil {
        panic(err)
    }
    
    // Downloads the first found image to the "images" directory with the file name
    // "example" (The file extension is determined by mimetypes inside the function)
    // If an image with the same name already exists in "images", it will be overwritten.
    path, err := imagesearch.DownloadImage(urls[0], "./images", "example") 
    if err != nil {
        panic(err)
    }

    // Searches for "example" and downloads the first 10 results into the "images" directory.
    // Returns a slice of all the image's absolute paths.
    // missing is the difference between the number of downloaded images and the limit.
    // missing is usually only non-zero with limits closer to or above 100
    paths, missing, err := imagesearch.Download("example", 10, "./images")
}

Credits

This library is inspired by the Python library google-images-download created by hardikvasa and maintained by joeclinton1, but ported to Go and with some quality of life improvements, such as being able to retrieve urls as well. Essentially, this package is a port of the Python library GoogleImageScraper to Go.

Documentation

Overview

A package designed to search Google Images based on the input query and arguments. Due to the limitations of using only a single request to fetch images, only a max of about 100 images can be found per request. If you need to find more than 100, one of the many packages using simulated browsers may work better. These images may be protected under copyright, and you shouldn't do anything punishable with them, like using them for commercial use.

Index

• Variables
• func Download(query string, limit int, dir string, arguments ...string) (paths []string, missing int, err error)
• func DownloadImage(url, dir, name string) (imgpath string, err error)
• func IsUnpackErr(err error) bool
• func Urls(query string, limit int, arguments ...string) (urls []string, err error)
• type Image
  • func Images(query string, limit int, arguments ...string) (images []Image, err error)

Variables

var (
	Color = struct {
		Red, Orange, Yellow, Green, Teal, Blue, Purple, Pink, White, Gray, Black, Brown string
	}{Red: "isc:red", Orange: "isc:orange", Yellow: "isc:yellow", Green: "isc:green", Teal: "isc:teel", Blue: "isc:blue", Purple: "isc:purple", Pink: "isc:pink", White: "isc:white", Gray: "isc:gray", Black: "isc:black", Brown: "isc:brown"}

	ColorType = struct {
		Color, Grayscale, Transparent string
	}{Color: "ic:full", Grayscale: "ic:gray", Transparent: "ic:trans"}

	License = struct {
		CreativeCommons, Other string
	}{CreativeCommons: "il:cl", Other: "il:ol"}

	Type = struct {
		Face, Photo, Clipart, Lineart, Animated string
	}{Face: "itp:face", Photo: "itp:photo", Clipart: "itp:clipart", Lineart: "itp:lineart", Animated: "itp:animated"}

	Time = struct {
		PastDay, PastWeek, PastMonth, PastYear string
	}{PastDay: "qdr:d", PastWeek: "qdr:w", PastMonth: "qdr:m", PastYear: "qdr:y"}

	AspectRatio = struct {
		Tall, Square, Wide, Panoramic string
	}{Tall: "iar:t", Square: "iar:s", Wide: "iar:w", Panoramic: "iar:xw"}

	Format = struct {
		Jpg, Gif, Png, Bmp, Svg, Webp, Ico, Raw string
	}{Jpg: "ift:jpg", Gif: "ift:gif", Png: "ift:png", Bmp: "ift:bmp", Svg: "ift:svg", Webp: "webp", Ico: "ift:ico", Raw: "ift:craw"}
)

These variables are all of the possible arguments that can be passed into Images, Download, and Urls. These are used by passing imagesearch.{Argument}.{Option} into the arguments parameter. For example:

urls, err := imagesearch.Urls("example", 0, imagesearch.Color.Red, imagesearch.License.CreativeCommons)

Functions

func Download

func Download(query string, limit int, dir string, arguments ...string) (paths []string, missing int, err error)

Searches for the given query along with the given argumetnts and downloads the images into the given directory. The amount of images does not exceed the limit unless the limit is 0, in which case it will download all images found. Returns a slice of the absolute paths of all downloaded images, along with the number of missing images.

The number of missing images is the difference between the limit and the actual number of images downloaded. This is only non-zero when the limit is higher than the number of downloadable images found.

func DownloadImage

func DownloadImage(url, dir, name string) (imgpath string, err error)

Given the url of the image, the directory to download to, and the name of the file *without extension*, this will find the type of image and download it to the given directory. Warning: This will overwrite any image file with the same name, if the extension matches, so make sure to keep the name unique. You can check if a file with the name already exists with the following code:

import (
    "path"
    "path/filepath"
)

func exists(dir, name string) bool {
    pat := path.Join(dir, name) + ".*"
    matches, _ := filepath.Glob(pat)
    return len(matches) > 0
}

func IsUnpackErr

func IsUnpackErr(err error) bool

Checks if an error is an unpacking error. An unpacking error is generally thrown when Google changes their JSON structure, or on certain internet connections, when the specific header does not work. If you believe Google changed their JSON structure, please submit a bug report at https://github.com/Jibble330/imagesearch/issues, and I will try to fix this asap.

func Urls

func Urls(query string, limit int, arguments ...string) (urls []string, err error)

Searches for the query along with the given arguments, and returns a slice of the image urls. The amount of images does not exceed the limit unless the limit is 0, in which case it will return all urls found.

Types

type Image

type Image struct {
	// Image URL
	Url string `json:"url"`

	// URL the image was found at
	Source string `json:"source"`

	// Base of the source URL
	Base string `json:"base"`
}

Contains information about an image including the url of the image, the url of the source, and the website it came from. Example:

Image {
    Url: "www.example.com/static/image.png"
    Source: "www.example.com/article"
    Base: "example.com"
}

func Images

func Images(query string, limit int, arguments ...string) (images []Image, err error)

Searches for the query along with the given arguments, and returns a slice of Image objects. The amount of images does not exceed the limit unless the limit is 0, in which case it will return all images found.