search1api 0.2.1__tar.gz → 0.4.0__tar.gz

search1api-0.4.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.4.0 - 2026-10-12
+
+Breaking: search/news engine-specific fields move from each result's top level to optional `metadata` (`kind`, `stars`, `language`, `num_comments`, `points`, `story_url`). Read e.g. `result.metadata.stars` instead of `result.stars`. `published_date` stays at the top level. No legacy field aliases.

{search1api-0.2.1 → search1api-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: search1api
-Version: 0.2.1
+Version: 0.4.0
 Summary: Official Python client for Search1API
 Project-URL: Homepage, https://s1.dev
 Project-URL: Documentation, https://s1.dev/docs/integrations/sdks
@@ -77,6 +77,16 @@ for result in response["results"]:
     print(result["title"], result["link"])
 ```
 
+`search_service` selects one engine (`google` by default), for example `bing`,
+`bingcn`, `yandex`, `reddit`, `github`, `arxiv`, `wikipedia`, or `grokipedia`.
+`page` requests a later results page on engines with native pagination
+(`bing`, `bingcn`, `baidu`, `grokipedia`). Results carry `published_date` when the source
+exposes one. Engine-specific fields are in each result's optional `metadata`:
+GitHub uses `metadata.kind`, `metadata.stars`, `metadata.language`, and
+`metadata.num_comments`; Hacker News news results use `metadata.story_url`,
+`metadata.points`, and `metadata.num_comments`. The former top-level paths
+are removed in 0.4.0; `published_date` stays at the top level.
+
 Use the client as a context manager when it owns the HTTP connection pool:
 
 ```python
@@ -93,6 +103,24 @@ async with AsyncSearch1API() as client:
     response = await client.search("latest AI agent frameworks")
 ```
 
+## Ask
+
+`ask` sends a natural-language request and lets Search1API choose the engines
+and time window. It returns at most 10 results ranked by relevance, and
+`intent` reports what was searched:
+
+```python
+answer = client.ask("What are developers saying about Bun 1.3 this month?")
+
+print(answer["intent"]["sources"], answer["intent"]["time_range"])
+for result in answer["results"]:
+    print(result["relevance"], result["source"], result["title"], result["link"])
+```
+
+A completed request costs 5 credits. Ask is not available with pay-per-request
+payments, and its default timeout is 45 seconds. Use `search` when you already
+know which engine and keywords you want.
+
 ## Deepcrawl
 
 `deepcrawl` starts a task and waits for it to finish:
@@ -126,7 +154,21 @@ The clients also support news, crawl, sitemap, trending, extract, usage, and
 batch operations exposed by the Search1API HTTP API. Requests time out after
 30 seconds and retry `429` and transient `5xx` responses twice by default.
 Authentication, payment, and validation errors are never retried. Deepcrawl
-task creation is not retried automatically because it is not idempotent.
+task creation and feedback are not retried automatically because they are not
+idempotent.
+
+## Feedback
+
+`feedback` reports a Search1API problem, missing capability, or confusing
+documentation. It is free. Do not include credentials or personal data:
+
+```python
+client.feedback(
+    "Results for this query have no publication dates",
+    category="feature_request",
+    request_id="the x-search1api-request-id of the original request",
+)
+```
 
 ## Development
 

{search1api-0.2.1 → search1api-0.4.0}/README.md

@@ -26,6 +26,16 @@ for result in response["results"]:
     print(result["title"], result["link"])
 ```
 
+`search_service` selects one engine (`google` by default), for example `bing`,
+`bingcn`, `yandex`, `reddit`, `github`, `arxiv`, `wikipedia`, or `grokipedia`.
+`page` requests a later results page on engines with native pagination
+(`bing`, `bingcn`, `baidu`, `grokipedia`). Results carry `published_date` when the source
+exposes one. Engine-specific fields are in each result's optional `metadata`:
+GitHub uses `metadata.kind`, `metadata.stars`, `metadata.language`, and
+`metadata.num_comments`; Hacker News news results use `metadata.story_url`,
+`metadata.points`, and `metadata.num_comments`. The former top-level paths
+are removed in 0.4.0; `published_date` stays at the top level.
+
 Use the client as a context manager when it owns the HTTP connection pool:
 
 ```python
@@ -42,6 +52,24 @@ async with AsyncSearch1API() as client:
     response = await client.search("latest AI agent frameworks")
 ```
 
+## Ask
+
+`ask` sends a natural-language request and lets Search1API choose the engines
+and time window. It returns at most 10 results ranked by relevance, and
+`intent` reports what was searched:
+
+```python
+answer = client.ask("What are developers saying about Bun 1.3 this month?")
+
+print(answer["intent"]["sources"], answer["intent"]["time_range"])
+for result in answer["results"]:
+    print(result["relevance"], result["source"], result["title"], result["link"])
+```
+
+A completed request costs 5 credits. Ask is not available with pay-per-request
+payments, and its default timeout is 45 seconds. Use `search` when you already
+know which engine and keywords you want.
+
 ## Deepcrawl
 
 `deepcrawl` starts a task and waits for it to finish:
@@ -75,7 +103,21 @@ The clients also support news, crawl, sitemap, trending, extract, usage, and
 batch operations exposed by the Search1API HTTP API. Requests time out after
 30 seconds and retry `429` and transient `5xx` responses twice by default.
 Authentication, payment, and validation errors are never retried. Deepcrawl
-task creation is not retried automatically because it is not idempotent.
+task creation and feedback are not retried automatically because they are not
+idempotent.
+
+## Feedback
+
+`feedback` reports a Search1API problem, missing capability, or confusing
+documentation. It is free. Do not include credentials or personal data:
+
+```python
+client.feedback(
+    "Results for this query have no publication dates",
+    category="feature_request",
+    request_id="the x-search1api-request-id of the original request",
+)
+```
 
 ## Development