Skip to content

Copyseeker

Classes

Copyseeker

Bases: BaseSearchEngine[CopyseekerResponse]

API client for the Copyseeker image search engine.

Used for performing reverse image searches using Copyseeker service.

Attributes:

Name Type Description
base_url str

The base URL for Copyseeker searches.
Source code in PicImageSearch/engines/copyseeker.py 
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
class Copyseeker(BaseSearchEngine[CopyseekerResponse]):
    """API client for the Copyseeker image search engine.

    Used for performing reverse image searches using Copyseeker service.

    Attributes:
        base_url (str): The base URL for Copyseeker searches.
    """

    def __init__(
        self, base_url: str = "https://api.copyseeker.net", **request_kwargs: Any
    ):
        """Initializes a Copyseeker API client.

        Args:
            base_url (str): The base URL for Copyseeker searches.
            **request_kwargs (Any): Additional arguments for network requests.
        """
        super().__init__(base_url, **request_kwargs)

    async def _get_discovery_id(
        self, url: Optional[str] = None, file: Union[str, bytes, Path, None] = None
    ) -> Optional[str]:
        """Retrieves a discovery ID from Copyseeker for image search.

        This method handles two search scenarios:
            1. Search by image URL
            2. Search by uploading a local image file

        Args:
            url (Optional[str]): URL of the image to search.
            file (Union[str, bytes, Path, None]): Local image file, can be a path string, bytes data, or Path object.

        Returns:
            Optional[str]: The discovery ID if successful, None otherwise.

        Note:
            - The discovery ID is required for retrieving search results.
        """

        data = {"discoveryType": "ReverseImageSearch"}

        if url:
            data["imageUrl"] = url
            resp = await self._make_request(
                method="post",
                endpoint="OnTriggerDiscoveryByUrl",
                json=data,
            )
        elif file:
            files = {"file": read_file(file)}
            resp = await self._make_request(
                method="post",
                endpoint="OnTriggerDiscoveryByFile",
                data=data,
                files=files,
            )

        resp_json = json_loads(resp.text)
        return resp_json.get("discoveryId")  # type: ignore

    async def search(
        self,
        url: Optional[str] = None,
        file: Union[str, bytes, Path, None] = None,
        **kwargs: Any,
    ) -> CopyseekerResponse:
        """Performs a reverse image search on Copyseeker.

        This method supports two ways of searching:
            1. Search by image URL
            2. Search by uploading a local image file

        The search process involves two steps:
            1. Obtaining a discovery ID
            2. Retrieving search results using the discovery ID

        Args:
            url (Optional[str]): URL of the image to search.
            file (Union[str, bytes, Path, None]): Local image file, can be a path string, bytes data, or Path object.
            **kwargs (Any): Additional arguments passed to the parent class.

        Returns:
            CopyseekerResponse: An object containing search results and metadata.
                Returns an empty response if discovery ID cannot be obtained.

        Raises:
            ValueError: If neither `url` nor `file` is provided.

        Note:
            - Only one of `url` or `file` should be provided.
            - The search process involves multiple HTTP requests to Copyseeker's API.
        """
        self._validate_args(url, file)

        discovery_id = await self._get_discovery_id(url, file)
        if discovery_id is None:
            return CopyseekerResponse({}, "")

        data = {"discoveryId": discovery_id, "hasBlocker": False}

        resp = await self._make_request(
            method="post", endpoint="OnProvideDiscovery", json=data
        )
        resp_json = json_loads(resp.text)
        return CopyseekerResponse(resp_json, resp.url)

Functions

__init__(base_url='https://api.copyseeker.net', **request_kwargs)

Initializes a Copyseeker API client.

Parameters:

Name Type Description Default
base_url str

The base URL for Copyseeker searches.

 'https://api.copyseeker.net'
**request_kwargs Any

Additional arguments for network requests.

 {}
Source code in PicImageSearch/engines/copyseeker.py 
19
20
21
22
23
24
25
26
27
28
def __init__(
    self, base_url: str = "https://api.copyseeker.net", **request_kwargs: Any
):
    """Initializes a Copyseeker API client.

    Args:
        base_url (str): The base URL for Copyseeker searches.
        **request_kwargs (Any): Additional arguments for network requests.
    """
    super().__init__(base_url, **request_kwargs)
search(url=None, file=None, **kwargs) async

Performs a reverse image search on Copyseeker.

This method supports two ways of searching
  1. Search by image URL
  2. Search by uploading a local image file
The search process involves two steps
  1. Obtaining a discovery ID
  2. Retrieving search results using the discovery ID

Parameters:

Name Type Description Default
url Optional[str]

URL of the image to search.

 None
file Union[str, bytes, Path, None]

Local image file, can be a path string, bytes data, or Path object.

 None
**kwargs Any

Additional arguments passed to the parent class.

 {}

Returns:

Name Type Description
CopyseekerResponse CopyseekerResponse

An object containing search results and metadata. Returns an empty response if discovery ID cannot be obtained.

Raises:

Type Description
ValueError

If neither url nor file is provided.
Note
  • Only one of url or file should be provided.
  • The search process involves multiple HTTP requests to Copyseeker's API.
Source code in PicImageSearch/engines/copyseeker.py 
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
async def search(
    self,
    url: Optional[str] = None,
    file: Union[str, bytes, Path, None] = None,
    **kwargs: Any,
) -> CopyseekerResponse:
    """Performs a reverse image search on Copyseeker.

    This method supports two ways of searching:
        1. Search by image URL
        2. Search by uploading a local image file

    The search process involves two steps:
        1. Obtaining a discovery ID
        2. Retrieving search results using the discovery ID

    Args:
        url (Optional[str]): URL of the image to search.
        file (Union[str, bytes, Path, None]): Local image file, can be a path string, bytes data, or Path object.
        **kwargs (Any): Additional arguments passed to the parent class.

    Returns:
        CopyseekerResponse: An object containing search results and metadata.
            Returns an empty response if discovery ID cannot be obtained.

    Raises:
        ValueError: If neither `url` nor `file` is provided.

    Note:
        - Only one of `url` or `file` should be provided.
        - The search process involves multiple HTTP requests to Copyseeker's API.
    """
    self._validate_args(url, file)

    discovery_id = await self._get_discovery_id(url, file)
    if discovery_id is None:
        return CopyseekerResponse({}, "")

    data = {"discoveryId": discovery_id, "hasBlocker": False}

    resp = await self._make_request(
        method="post", endpoint="OnProvideDiscovery", json=data
    )
    resp_json = json_loads(resp.text)
    return CopyseekerResponse(resp_json, resp.url)

Functions