nosible 0.2.3__py3-none-any.whl → 0.2.5__py3-none-any.whl

nosible/classes/result.py

@@ -10,6 +10,7 @@ if TYPE_CHECKING:
     from nosible.classes.result_set import ResultSet
 else:
     ResultSet = None
+import warnings
 
 
 @dataclass(init=True, repr=True, eq=True, frozen=False)
@@ -39,6 +40,32 @@ class Result:
         The language code of the content (e.g., 'en' for English).
     similarity : float, optional
         Similarity score with respect to a query or reference.
+    brand_safety : str, optional
+        Whether it is safe, sensitive, or unsafe to advertise on this content.
+    language : str, optional
+        Language code to use in search (ISO 639-1 language code).
+    continent : str, optional
+        Continent the results must come from (e.g., "Europe", "Asia").
+    region : str, optional
+        Region or subcontinent the results must come from (e.g., "Southern Africa", "Caribbean").
+    country : str, optional
+        Country the results must come from.
+    sector : str, optional
+        GICS Sector the results must relate to (e.g., "Energy", "Information Technology").
+    industry_group : str, optional
+        GICS Industry group the results must relate to (e.g., "Automobiles & Components", "Insurance").
+    industry : str, optional
+        GICS Industry the results must relate to (e.g., "Consumer Finance", "Passenger Airlines").
+    sub_industry : str, optional
+        GICS Sub-industry classification of the content's subject.
+    iab_tier_1 : str, optional
+        IAB Tier 1 category for the content.
+    iab_tier_2 : str, optional
+        IAB Tier 2 category for the content.
+    iab_tier_3 : str, optional
+        IAB Tier 3 category for the content.
+    iab_tier_4 : str, optional
+        IAB Tier 4 category for the content.
 
     Examples
     --------
@@ -84,6 +111,30 @@ class Result:
     """Similarity score with respect to a query or reference."""
     url_hash: str | None = None
     """A hash of the URL for quick comparisons."""
+    brand_safety: str | None = None
+    """Whether it is safe, sensitive, or unsafe to advertise on this content."""
+    continent: str | None = None
+    """Continent the results must come from (e.g., "Europe", "Asia")."""
+    region: str | None = None
+    """Region or subcontinent the results must come from (e.g., "Southern Africa", "Caribbean")."""
+    country: str | None = None
+    """Country the results must come from."""
+    sector: str | None = None
+    """GICS Sector the results must relate to (e.g., "Energy", "Information Technology")."""
+    industry_group: str | None = None
+    """GICS Industry group the results must relate to (e.g., "Automobiles & Components", "Insurance")."""
+    industry: str | None = None
+    """GICS Industry the results must relate to (e.g., "Consumer Finance", "Passenger Airlines")."""
+    sub_industry: str | None = None
+    """GICS Sub-industry classification of the content's subject."""
+    iab_tier_1: str | None = None
+    """IAB Tier 1 category for the content."""
+    iab_tier_2: str | None = None
+    """IAB Tier 2 category for the content."""
+    iab_tier_3: str | None = None
+    """IAB Tier 3 category for the content."""
+    iab_tier_4: str | None = None
+    """IAB Tier 4 category for the content."""
 
     def __str__(self) -> str:
         """
@@ -332,20 +383,32 @@ class Result:
         n_results: int = 100,
         n_probes: int = 30,
         n_contextify: int = 128,
-        algorithm: str = "hybrid-2",
+        algorithm: str = "hybrid-3",
         publish_start: str = None,
         publish_end: str = None,
-        include_netlocs: list = None,
-        exclude_netlocs: list = None,
         visited_start: str = None,
         visited_end: str = None,
         certain: bool = None,
-        include_languages: list = None,
-        exclude_languages: list = None,
+        include_netlocs: list = None,
+        exclude_netlocs: list = None,
         include_companies: list = None,
         exclude_companies: list = None,
         include_docs: list = None,
         exclude_docs: list = None,
+        brand_safety: str = None,
+        language: str = None,
+        continent: str = None,
+        region: str = None,
+        country: str = None,
+        sector: str = None,
+        industry_group: str = None,
+        industry: str = None,
+        sub_industry: str = None,
+        iab_tier_1: str = None,
+        iab_tier_2: str = None,
+        iab_tier_3: str = None,
+        iab_tier_4: str = None,
+        *args, **kwargs
     ) -> ResultSet:
         """
         Find similar search results based on the content or metadata of this Result.
@@ -381,10 +444,6 @@ class Result:
             List of netlocs (domains) to include in the search. (Max: 50)
         exclude_netlocs : list of str, optional
             List of netlocs (domains) to exclude in the search. (Max: 50)
-        include_languages : list of str, optional
-            Languages to include in the search. (Max: 50, ISO 639-1 language codes).
-        exclude_languages : list of str, optional
-            Language codes to exclude in the search (Max: 50, ISO 639-1 language codes).
         include_companies : list of str, optional
             Google KG IDs of public companies to require (Max: 50).
         exclude_companies : list of str, optional
@@ -393,6 +452,32 @@ class Result:
             URL hashes of docs to include (Max: 50).
         exclude_docs : list of str, optional
             URL hashes of docs to exclude (Max: 50).
+        brand_safety : str, optional
+            Whether it is safe, sensitive, or unsafe to advertise on this content.
+        language : str, optional
+            Language code to use in search (ISO 639-1 language code).
+        continent : str, optional
+            Continent the results must come from (e.g., "Europe", "Asia").
+        region : str, optional
+            Region or subcontinent the results must come from (e.g., "Southern Africa", "Caribbean").
+        country : str, optional
+            Country the results must come from.
+        sector : str, optional
+            GICS Sector the results must relate to (e.g., "Energy", "Information Technology").
+        industry_group : str, optional
+            GICS Industry group the results must relate to (e.g., "Automobiles & Components", "Insurance").
+        industry : str, optional
+            GICS Industry the results must relate to (e.g., "Consumer Finance", "Passenger Airlines").
+        sub_industry : str, optional
+            GICS Sub-industry classification of the content's subject.
+        iab_tier_1 : str, optional
+            IAB Tier 1 category for the content.
+        iab_tier_2 : str, optional
+            IAB Tier 2 category for the content.
+        iab_tier_3 : str, optional
+            IAB Tier 3 category for the content.
+        iab_tier_4 : str, optional
+            IAB Tier 4 category for the content.
 
         Returns
         -------
@@ -413,6 +498,17 @@ class Result:
         ...     result = Result(url="https://example.com", title="Example Domain")  # doctest: +SKIP
         ...     similar_results = result.similar(client=nos)  # doctest: +SKIP
         """
+        if "include_languages" in kwargs:
+            warnings.warn(
+                "The 'include_languages' parameter is deprecated and will be removed in a future release. "
+                "Please use the parameter 'language' instead.",
+            )
+        if "exclude_languages" in kwargs:
+            warnings.warn(
+                "The 'exclude_languages' parameter is deprecated and will be removed in a future release. "
+                "Please use the parameter 'language' instead.",
+            )
+
         if client is None:
             raise ValueError("A Nosible client instance must be provided as 'client'.")
         if not self.url:
@@ -436,14 +532,25 @@ class Result:
                 visited_start=visited_start,
                 visited_end=visited_end,
                 certain=certain,
-                include_languages=include_languages,
-                exclude_languages=exclude_languages,
                 include_companies=include_companies,
                 exclude_companies=exclude_companies,
                 include_docs=include_docs,
                 exclude_docs=exclude_docs,
+                brand_safety=brand_safety,
+                language=language,
+                continent=continent,
+                region=region,
+                country=country,
+                sector=sector,
+                industry_group=industry_group,
+                industry=industry,
+                sub_industry=sub_industry,
+                iab_tier_1=iab_tier_1,
+                iab_tier_2=iab_tier_2,
+                iab_tier_3=iab_tier_3,
+                iab_tier_4=iab_tier_4,
             )
-            return client.search(search=s)
+            return client.fast_search(search=s)
         except Exception as e:
             raise RuntimeError(f"Failed to find similar results for title '{self.title}': {e}") from e
 

nosible/classes/result_set.py

@@ -57,6 +57,19 @@ class ResultSet(Iterator[Result]):
         "language",
         "similarity",
         "url_hash",
+        "brand_safety",
+        "language",
+        "continent",
+        "region",
+        "country",
+        "sector",
+        "industry_group",
+        "industry",
+        "sub_industry",
+        "iab_tier_1",
+        "iab_tier_2",
+        "iab_tier_3",
+        "iab_tier_4",
     ]
 
     results: list[Result] = field(default_factory=list)
@@ -310,7 +323,7 @@ class ResultSet(Iterator[Result]):
         >>> from nosible import Nosible
         >>> from nosible import ResultSet
         >>> with Nosible() as nos:
-        ...     results: ResultSet = nos.search(question="Aircraft Manufacturing", n_results=10)
+        ...     results: ResultSet = nos.fast_search(question="Aircraft Manufacturing", n_results=10)
         ...     inner = results.find_in_search_results("embraer", top_k=5)
         >>> print(f"Top {len(inner)} hits for “embraer” within the initial results:")
         Top 5 hits for “embraer” within the initial results:
@@ -409,7 +422,7 @@ class ResultSet(Iterator[Result]):
         >>> from nosible import Nosible
         >>> from nosible import Result, ResultSet
         >>> with Nosible() as nos:
-        ...     results: ResultSet = nos.search(question="Aircraft Manufacturing", n_results=100)
+        ...     results: ResultSet = nos.fast_search(question="Aircraft Manufacturing", n_results=100)
         ...     summary = results.analyze(by="language")
         ...     print(summary)
         {'en': 100}
@@ -507,7 +520,7 @@ class ResultSet(Iterator[Result]):
         return {str(row[0]): int(row[1]) for row in sorted_vc.rows()}
 
     # Conversion methods
-    def to_csv(self, file_path: str | None = None, delimiter: str = ",", encoding: str = "utf-8") -> str:
+    def write_csv(self, file_path: str | None = None, delimiter: str = ",", encoding: str = "utf-8") -> str:
         """
         Serialize the search results to a CSV file.
 
@@ -542,7 +555,7 @@ class ResultSet(Iterator[Result]):
         ...     Result(url="https://openai.com", title="OpenAI"),
         ... ]
         >>> search_results = ResultSet(results)
-        >>> path = search_results.to_csv("out.csv")
+        >>> path = search_results.write_csv("out.csv")
         >>> path.endswith(".csv")
         True
         """
@@ -622,7 +635,7 @@ class ResultSet(Iterator[Result]):
         except Exception as e:
             raise RuntimeError(f"Failed to convert search results to Pandas DataFrame: {e}") from e
 
-    def to_json(self, file_path: str | None = None) -> str | bytes:
+    def write_json(self, file_path: str | None = None) -> str | bytes:
         """
         Serialize the search results to a JSON string and optionally write to disk.
 
@@ -648,11 +661,11 @@ class ResultSet(Iterator[Result]):
         ...     Result(url="https://openai.com", title="OpenAI"),
         ... ]
         >>> search_results = ResultSet(results)
-        >>> json_str = search_results.to_json()
+        >>> json_str = search_results.write_json()
         >>> isinstance(json_str, str)
         True
         >>> # Optionally write to file
-        >>> path = search_results.to_json(file_path="results.json")
+        >>> path = search_results.write_json(file_path="results.json")
         >>> path.endswith(".json")
         True
         """
@@ -747,7 +760,7 @@ class ResultSet(Iterator[Result]):
         except Exception as e:
             raise RuntimeError(f"Failed to convert results to dict: {e}") from e
 
-    def to_ndjson(self, file_path: str | None = None) -> str:
+    def write_ndjson(self, file_path: str | None = None) -> str:
         """
         Serialize search results to newline-delimited JSON (NDJSON) format.
 
@@ -777,11 +790,11 @@ class ResultSet(Iterator[Result]):
         ...     Result(url="https://openai.com", title="OpenAI"),
         ... ]
         >>> search_results = ResultSet(results)
-        >>> ndjson_str = search_results.to_ndjson()
+        >>> ndjson_str = search_results.write_ndjson()
         >>> print(ndjson_str.splitlines()[0])  # doctest: +ELLIPSIS
         {"url":"https://example.com","title":"Example Domain","description":null,"netloc":null..."url_hash":null}
         >>> # Optionally write to file
-        >>> path = search_results.to_ndjson(file_path="results.ndjson")
+        >>> path = search_results.write_ndjson(file_path="results.ndjson")
         >>> path.endswith(".ndjson")
         True
         """
@@ -802,7 +815,7 @@ class ResultSet(Iterator[Result]):
                 raise RuntimeError(f"Failed to write NDJSON to '{file_path}': {e}") from e
         return "\n".join(ndjson_lines) + "\n"
 
-    def to_parquet(self, file_path: str | None = None) -> str:
+    def write_parquet(self, file_path: str | None = None) -> str:
         """
         Serialize the search results to Apache Parquet format using Polars.
 
@@ -832,7 +845,7 @@ class ResultSet(Iterator[Result]):
         ...     Result(url="https://openai.com", title="OpenAI"),
         ... ]
         >>> search_results = ResultSet(results)
-        >>> parquet_path = search_results.to_parquet("my_results.parquet")
+        >>> parquet_path = search_results.write_parquet("my_results.parquet")
         >>> parquet_path.endswith(".parquet")
         True
         """
@@ -843,7 +856,7 @@ class ResultSet(Iterator[Result]):
             raise RuntimeError(f"Failed to write Parquet to '{out}': {e}") from e
         return out
 
-    def to_arrow(self, file_path: str | None = None) -> str:
+    def write_ipc(self, file_path: str | None = None) -> str:
         """
         Serialize the search results to Apache Arrow IPC (Feather) format using Polars.
 
@@ -873,7 +886,7 @@ class ResultSet(Iterator[Result]):
         ...     Result(url="https://openai.com", title="OpenAI"),
         ... ]
         >>> search_results = ResultSet(results)
-        >>> arrow_path = search_results.to_arrow("my_results.arrow")
+        >>> arrow_path = search_results.write_ipc("my_results.arrow")
         >>> arrow_path.endswith(".arrow")
         True
         """
@@ -884,7 +897,7 @@ class ResultSet(Iterator[Result]):
             raise RuntimeError(f"Failed to write Arrow IPC to '{out}': {e}") from e
         return out
 
-    def to_duckdb(self, file_path: str | None = None, table_name: str = "results") -> str:
+    def write_duckdb(self, file_path: str | None = None, table_name: str = "results") -> str:
         """
         Serialize the search results to a DuckDB database file and table.
 
@@ -917,7 +930,7 @@ class ResultSet(Iterator[Result]):
         ...     Result(url="https://openai.com", title="OpenAI"),
         ... ]
         >>> search_results = ResultSet(results)
-        >>> db_path = search_results.to_duckdb(file_path="my_results.duckdb", table_name="search_table")
+        >>> db_path = search_results.write_duckdb(file_path="my_results.duckdb", table_name="search_table")
         >>> db_path.endswith(".duckdb")
         True
         """
@@ -939,7 +952,7 @@ class ResultSet(Iterator[Result]):
 
     # Loading from disk
     @classmethod
-    def from_csv(cls, file_path: str) -> ResultSet:
+    def read_csv(cls, file_path: str) -> ResultSet:
         """
         Load search results from a CSV file using Polars.
 
@@ -971,7 +984,7 @@ class ResultSet(Iterator[Result]):
         ...         {"url": "https://openai.com", "title": "OpenAI", "description": "AI research"},
         ...     ]
         ... ).write_csv("data.csv")
-        >>> results = ResultSet.from_csv("data.csv")
+        >>> results = ResultSet.read_csv("data.csv")
         >>> isinstance(results, ResultSet)
         True
         >>> len(results)
@@ -1007,7 +1020,7 @@ class ResultSet(Iterator[Result]):
         return cls(results)
 
     @classmethod
-    def from_json(cls, file_path: str) -> ResultSet:
+    def read_json(cls, file_path: str) -> ResultSet:
         """
         Load search results from a JSON file.
 
@@ -1039,7 +1052,7 @@ class ResultSet(Iterator[Result]):
         ...         ],
         ...         f,
         ...     )
-        >>> results = ResultSet.from_json("data.json")
+        >>> results = ResultSet.read_json("data.json")
         >>> isinstance(results, ResultSet)
         True
         >>> len(results)
@@ -1147,7 +1160,7 @@ class ResultSet(Iterator[Result]):
         return cls.from_polars(pl_df)
 
     @classmethod
-    def from_ndjson(cls, file_path: str) -> ResultSet:
+    def read_ndjson(cls, file_path: str) -> ResultSet:
         """
         Load search results from a newline-delimited JSON (NDJSON) file.
 
@@ -1181,7 +1194,7 @@ class ResultSet(Iterator[Result]):
         ...     f.write('{"url": "https://openai.com", "title": "OpenAI"}\\n')
         58
         49
-        >>> results = ResultSet.from_ndjson("data.ndjson")
+        >>> results = ResultSet.read_ndjson("data.ndjson")
         >>> isinstance(results, ResultSet)
         True
         >>> len(results)
@@ -1219,7 +1232,7 @@ class ResultSet(Iterator[Result]):
         return cls(results)
 
     @classmethod
-    def from_parquet(cls, file_path: str) -> ResultSet:
+    def read_parquet(cls, file_path: str) -> ResultSet:
         """
         Load search results from a Parquet file using Polars.
 
@@ -1250,7 +1263,7 @@ class ResultSet(Iterator[Result]):
         ...     ]
         ... )
         >>> df.write_parquet("sample.parquet")
-        >>> results = ResultSet.from_parquet("sample.parquet")
+        >>> results = ResultSet.read_parquet("sample.parquet")
         >>> isinstance(results, ResultSet)
         True
         >>> len(results)
@@ -1270,7 +1283,7 @@ class ResultSet(Iterator[Result]):
             raise RuntimeError(f"Failed to create ResultSet from Parquet data in '{file_path}': {e}") from e
 
     @classmethod
-    def from_arrow(cls, file_path: str) -> ResultSet:
+    def read_ipc(cls, file_path: str) -> ResultSet:
         """
         Load search results from an Apache Arrow IPC (Feather) file using Polars.
 
@@ -1301,7 +1314,7 @@ class ResultSet(Iterator[Result]):
         ...     ]
         ... )
         >>> df.write_ipc("sample.arrow")
-        >>> results = ResultSet.from_arrow("sample.arrow")
+        >>> results = ResultSet.read_ipc("sample.arrow")
         >>> isinstance(results, ResultSet)
         True
         >>> len(results)
@@ -1321,7 +1334,7 @@ class ResultSet(Iterator[Result]):
             raise RuntimeError(f"Failed to create ResultSet from Arrow data in '{file_path}': {e}") from e
 
     @classmethod
-    def from_duckdb(cls, file_path: str) -> ResultSet:
+    def read_duckdb(cls, file_path: str) -> ResultSet:
         """
         Load search results from a DuckDB database file.
 
@@ -1354,8 +1367,8 @@ class ResultSet(Iterator[Result]):
         ...     Result(url="https://openai.com", title="OpenAI", similarity=0.99),
         ... ]
         >>> search_results = ResultSet(results)
-        >>> db_path = search_results.to_duckdb(file_path="results.duckdb", table_name="search_results")
-        >>> loaded = ResultSet.from_duckdb("results.duckdb")
+        >>> db_path = search_results.write_duckdb(file_path="results.duckdb", table_name="search_results")
+        >>> loaded = ResultSet.read_duckdb("results.duckdb")
         >>> isinstance(loaded, ResultSet)
         True
         >>> len(loaded)

nosible/classes/search.py

@@ -55,10 +55,6 @@ class Search:
         List of netlocs (domains) to include in the search. (Max 50)
     exclude_netlocs : list of str, optional
         List of netlocs (domains) to exclude in the search. (Max 50)
-    include_languages : list of str, optional
-        Languages to include in the search. (Max 50, ISO 639-1 language codes).
-    exclude_languages : list of str, optional
-        Language codes to exclude in the search (Max 50, ISO 639-1 language codes).
     include_companies : list of str, optional
         Google KG IDs of public companies to require (Max 50).
     exclude_companies : list of str, optional
@@ -67,6 +63,32 @@ class Search:
         URL hashes of docs to include (Max 50).
     exclude_docs : list of str, optional
         URL hashes of docs to exclude (Max 50).
+    brand_safety : str, optional
+        Whether it is safe, sensitive, or unsafe to advertise on this content.
+    language : str, optional
+        Language code to use in search (ISO 639-1 language code).
+    continent : str, optional
+        Continent the results must come from (e.g., "Europe", "Asia").
+    region : str, optional
+        Region or subcontinent the results must come from (e.g., "Southern Africa", "Caribbean").
+    country : str, optional
+        Country the results must come from.
+    sector : str, optional
+        GICS Sector the results must relate to (e.g., "Energy", "Information Technology").
+    industry_group : str, optional
+        GICS Industry group the results must relate to (e.g., "Automobiles & Components", "Insurance").
+    industry : str, optional
+        GICS Industry the results must relate to (e.g., "Consumer Finance", "Passenger Airlines").
+    sub_industry : str, optional
+        GICS Sub-industry classification of the content's subject.
+    iab_tier_1 : str, optional
+        IAB Tier 1 category for the content.
+    iab_tier_2 : str, optional
+        IAB Tier 2 category for the content.
+    iab_tier_3 : str, optional
+        IAB Tier 3 category for the content.
+    iab_tier_4 : str, optional
+        IAB Tier 4 category for the content.
 
     Examples
     --------
@@ -75,7 +97,7 @@ class Search:
     >>> search = Search(
     ...     question="What is Python?",
     ...     n_results=5,
-    ...     include_languages=["en"],
+    ...     language="en",
     ...     publish_start="2023-01-01",
     ...     publish_end="2023-12-31",
     ...     certain=True,
@@ -120,10 +142,6 @@ class Search:
     """List of netlocs (domains) to include in the search (Max 50)."""
     exclude_netlocs: list[str] | None = None
     """List of netlocs (domains) to exclude in the search (Max 50)."""
-    include_languages: list[str] | None = None
-    """Languages to include in the search. (Max 50)"""
-    exclude_languages: list[str] | None = None
-    """Language codes to exclude in the search (Max 50)"""
     include_companies: list[str] | None = None
     """Google KG IDs of public companies to require (Max 50)."""
     exclude_companies: list[str] | None = None
@@ -132,6 +150,32 @@ class Search:
     """URL hashes of docs to include (Max 50)."""
     exclude_docs: list[str] | None = None
     """URL hashes of docs to exclude (Max 50)."""
+    brand_safety: str | None = None
+    """Whether it is safe, sensitive, or unsafe to advertise on this content."""
+    language: str | None = None
+    """Language code to use in search (ISO 639-1 language code)."""
+    continent: str | None = None
+    """Continent the results must come from (e.g., "Europe", "Asia")."""
+    region: str | None = None
+    """Region or subcontinent the results must come from (e.g., "Southern Africa", "Caribbean")."""
+    country: str | None = None
+    """Country the results must come from."""
+    sector: str | None = None
+    """GICS Sector the results must relate to (e.g., "Energy", "Information Technology")."""
+    industry_group: str | None = None
+    """GICS Industry group the results must relate to (e.g., "Automobiles & Components", "Insurance")."""
+    industry: str | None = None
+    """GICS Industry the results must relate to (e.g., "Consumer Finance", "Passenger Airlines")."""
+    sub_industry: str | None = None
+    """GICS Sub-industry classification of the content's subject."""
+    iab_tier_1: str | None = None
+    """IAB Tier 1 category for the content."""
+    iab_tier_2: str | None = None
+    """IAB Tier 2 category for the content."""
+    iab_tier_3: str | None = None
+    """IAB Tier 3 category for the content."""
+    iab_tier_4: str | None = None
+    """IAB Tier 4 category for the content."""
 
     _FIELDS = [
         "question",
@@ -147,17 +191,28 @@ class Search:
         "autogenerate_expansions",
         "publish_start",
         "publish_end",
-        "include_netlocs",
-        "exclude_netlocs",
         "visited_start",
         "visited_end",
         "certain",
-        "include_languages",
-        "exclude_languages",
+        "include_netlocs",
+        "exclude_netlocs",
         "include_companies",
         "exclude_companies",
         "include_docs",
         "exclude_docs",
+        "brand_safety",
+        "language",
+        "continent",
+        "region",
+        "country",
+        "sector",
+        "industry_group",
+        "industry",
+        "sub_industry",
+        "iab_tier_1",
+        "iab_tier_2",
+        "iab_tier_3",
+        "iab_tier_4",
     ]
 
     def __str__(self) -> str:
@@ -220,7 +275,7 @@ class Search:
         Examples
         --------
         >>> search = Search(
-        ...     question="What is Python?", n_results=5, include_languages=["en"], publish_start="2023-01-01"
+        ...     question="What is Python?", n_results=5, language="en", publish_start="2023-01-01"
         ... )
         >>> search.to_dict()["question"]
         'What is Python?'
@@ -255,7 +310,7 @@ class Search:
         """
         return cls(**{field: data.get(field) for field in cls._FIELDS})
 
-    def save(self, path: str) -> None:
+    def write_json(self, path: str) -> None:
         """
         Save the current Search instance to a JSON file.
 
@@ -274,16 +329,16 @@ class Search:
         Examples
         --------
         >>> search = Search(
-        ...     question="What is Python?", n_results=5, include_languages=["en"], publish_start="2023-01-01"
+        ...     question="What is Python?", n_results=5, language="en", publish_start="2023-01-01"
         ... )
-        >>> search.save("search.json")
+        >>> search.write_json("search.json")
         """
         data = json_dumps(self.to_dict())
         with open(path, "w") as f:
             f.write(data)
 
     @classmethod
-    def load(cls, path: str) -> Search:
+    def read_json(cls, path: str) -> Search:
         """
         Load a Search instance from a JSON file.
 
@@ -299,7 +354,7 @@ class Search:
         Returns
         -------
         Search
-            An instance of the Search class initialized with the loaded parameters.
+            An instancex  of the Search class initialized with the loaded parameters.
 
         Raises
         ------
@@ -309,10 +364,10 @@ class Search:
         Save and load a Search instance:
 
         >>> search = Search(
-        ...     question="What is Python?", n_results=3, include_languages=["en"], publish_start="2023-01-01"
+        ...     question="What is Python?", n_results=3, language="en", publish_start="2023-01-01"
         ... )
-        >>> search.save("search.json")
-        >>> loaded_search = Search.load("search.json")
+        >>> search.write_json("search.json")
+        >>> loaded_search = Search.read_json("search.json")
         >>> print(loaded_search.question)
         What is Python?
         """