prismcrawl 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,14 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ venv/
5
+ dist/
6
+ build/
7
+ *.egg-info/
8
+ .pytest_cache/
9
+ .mypy_cache/
10
+ .ruff_cache/
11
+ .coverage
12
+ htmlcov/
13
+ .env
14
+ .DS_Store
@@ -0,0 +1,12 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+
5
+ First release.
6
+
7
+ - `PrismCrawl` and `AsyncPrismCrawl` clients for every PrismCrawl API endpoint
8
+ - Typed parameters and `TypedDict` response types generated from the OpenAPI spec
9
+ - `.get(request_id)` for request history and archived artifacts
10
+ - `.pages()` iterators for paginated endpoints
11
+ - `decode_html()` for `html=True` responses
12
+ - Automatic retries for rate limits, server errors, and connection failures
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 PrismCrawl
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,363 @@
1
+ Metadata-Version: 2.5
2
+ Name: prismcrawl
3
+ Version: 0.1.0
4
+ Summary: Official Python client for the PrismCrawl API: search results, places, app stores, products, and reviews as structured JSON.
5
+ Project-URL: Homepage, https://www.prismcrawl.com
6
+ Project-URL: Documentation, https://www.prismcrawl.com/docs
7
+ Project-URL: Repository, https://github.com/prismcrawl/prismcrawl-python
8
+ Project-URL: Issues, https://github.com/prismcrawl/prismcrawl-python/issues
9
+ Project-URL: Changelog, https://github.com/prismcrawl/prismcrawl-python/blob/main/CHANGELOG.md
10
+ Author-email: PrismCrawl <support@prismcrawl.com>
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Keywords: api,bing,google,maps,prismcrawl,reviews,scraping,search,serp
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.9
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Typing :: Typed
25
+ Requires-Python: >=3.9
26
+ Requires-Dist: httpx<1,>=0.23
27
+ Requires-Dist: typing-extensions>=4.7
28
+ Provides-Extra: html
29
+ Requires-Dist: brotli>=1.0; extra == 'html'
30
+ Description-Content-Type: text/markdown
31
+
32
+ # PrismCrawl Python SDK
33
+
34
+ The official Python client for [PrismCrawl](https://www.prismcrawl.com): live search results, AI answers, products, places, and reviews returned as structured JSON. Pass your API key and every PrismCrawl endpoint is one method call away. See the [API reference](https://www.prismcrawl.com/docs) for every endpoint and parameter.
35
+
36
+ ```python
37
+ from prismcrawl import PrismCrawl
38
+
39
+ client = PrismCrawl(api_key="YOUR_API_KEY")
40
+ results = client.google.search(query="best espresso machines")
41
+ ```
42
+
43
+ > **You need a PrismCrawl API key.** Sign up at [prismcrawl.com](https://www.prismcrawl.com) and create a key in the dashboard. It's free, and you don't need a card.
44
+ >
45
+ > **Pricing:** at volume, prepaid credit packages bring the price as low as **$0.15 per 1,000 successful requests**, and failed requests are free. That's **100x cheaper than SerpApi**. See [pricing](#pricing).
46
+
47
+ ## Why PrismCrawl
48
+
49
+ - **As low as $0.15 per 1,000 successful requests** at volume, 100x cheaper than SerpApi
50
+ - **You only pay for successes.** Failed requests are free.
51
+ - **Free to start:** 100 free credits, and you don't need a card
52
+ - **No subscription:** prepaid credit packages from $5, valid for 90 days
53
+ - **One key covers 26 endpoints:** Google, Bing, DuckDuckGo, Amazon, Google Maps, Apple Maps, Yelp, Tripadvisor, Google Play, and the Apple App Store
54
+ - **Answers from AI search engines:** Google AI Overviews, Google AI Mode, and Bing's AI overview with citations, at no additional charge
55
+ - **Live, uncached results:** every request fetches fresh data from the source
56
+ - **Proven at scale:** 99% successful response rate and more than 1 billion SERPs every month
57
+ - **See every request:** filter your request history in the [dashboard](https://www.prismcrawl.com) by query, provider, status, format, or date. You can check the parameters, timing, and credits for each request, copy it as cURL, rerun it, or download the saved HTML/JSON. Request details are kept for 90 days and the HTML/JSON for 30 days. To skip storing the results of a request, pass `zero_trace=True`.
58
+
59
+ ## What it can do
60
+
61
+ - **Search:** Google (including AI Overviews, AI Mode, Shopping, and Local results), Bing (including its AI overview with citations), DuckDuckGo, and Amazon
62
+ - **Maps and places:** Google Maps, Bing Maps, Apple Maps, DuckDuckGo Maps, Yelp, and Tripadvisor
63
+ - **Reviews:** Google Maps, Google contributors, Yelp, Tripadvisor, Apple Maps, Google Play, and the Apple App Store
64
+ - **App stores:** Google Play (apps, games, books, movies) and the Apple App Store: search, product details, and reviews
65
+ - **Shopping:** Google Shopping product details and merchant offers
66
+
67
+ ## SDK features
68
+
69
+ - Every endpoint, with sync and async clients
70
+ - Type hints for every parameter and response field, generated from the API spec
71
+ - Automatic retries for rate limits, server errors, and connection failures
72
+ - Page iterators for paginated endpoints
73
+ - Helpers for request history and source HTML
74
+
75
+ ## Installation
76
+
77
+ ```bash
78
+ pip install prismcrawl
79
+ ```
80
+
81
+ Requires Python 3.9 or later.
82
+
83
+ ## Quick start
84
+
85
+ Create an API key in the [PrismCrawl dashboard](https://www.prismcrawl.com). New accounts get 100 free credits.
86
+
87
+ ```python
88
+ from prismcrawl import PrismCrawl
89
+
90
+ client = PrismCrawl(api_key="YOUR_API_KEY")
91
+
92
+ response = client.google.search(query="best espresso machines", gl="us")
93
+
94
+ for result in response["data"]["content"]["results"]:
95
+ print(result["rank"], result["title"], result["url"])
96
+ ```
97
+
98
+ If you don't pass `api_key`, the client reads the `PRISMCRAWL_API_KEY` environment variable:
99
+
100
+ ```bash
101
+ export PRISMCRAWL_API_KEY="YOUR_API_KEY"
102
+ ```
103
+
104
+ ```python
105
+ client = PrismCrawl()
106
+ ```
107
+
108
+ More complete, runnable scripts are in [`examples/`](https://github.com/prismcrawl/prismcrawl-python/tree/main/examples).
109
+
110
+ ## Endpoints
111
+
112
+ Each endpoint is a callable object. Calling it runs the request. Every endpoint also has `.get(request_id)` to fetch a previous request, and paginated endpoints have `.pages(...)`.
113
+
114
+ | Method | API endpoint |
115
+ |---|---|
116
+ | `client.google.search(...)` | `POST /v1/google/search` |
117
+ | `client.google.maps.search(...)` | `POST /v1/google/maps/search` |
118
+ | `client.google.maps.reviews(...)` | `POST /v1/google/maps/reviews` |
119
+ | `client.google.contributor.reviews(...)` | `POST /v1/google/contributor/reviews` |
120
+ | `client.google.shopping.product(...)` | `POST /v1/google/shopping/product` |
121
+ | `client.google.play.apps.search(...)` | `POST /v1/google/play/apps/search` |
122
+ | `client.google.play.games.search(...)` | `POST /v1/google/play/games/search` |
123
+ | `client.google.play.books.search(...)` | `POST /v1/google/play/books/search` |
124
+ | `client.google.play.movies.search(...)` | `POST /v1/google/play/movies/search` |
125
+ | `client.google.play.product(...)` | `POST /v1/google/play/product` |
126
+ | `client.google.play.reviews(...)` | `POST /v1/google/play/reviews` |
127
+ | `client.bing.search(...)` | `POST /v1/microsoft/search` |
128
+ | `client.bing.maps.search(...)` | `POST /v1/microsoft/maps/search` |
129
+ | `client.duckduckgo.search(...)` | `POST /v1/duckduckgo/search` |
130
+ | `client.duckduckgo.maps.search(...)` | `POST /v1/duckduckgo/maps/search` |
131
+ | `client.amazon.search(...)` | `POST /v1/amazon/search` |
132
+ | `client.apple.maps.search(...)` | `POST /v1/apple/maps/search` |
133
+ | `client.apple.maps.reviews(...)` | `POST /v1/apple/maps/reviews` |
134
+ | `client.apple.app_store.search(...)` | `POST /v1/apple/app-store/search` |
135
+ | `client.apple.app_store.product(...)` | `POST /v1/apple/app-store/product` |
136
+ | `client.apple.app_store.reviews(...)` | `POST /v1/apple/app-store/reviews` |
137
+ | `client.yelp.search(...)` | `POST /v1/yelp/search` |
138
+ | `client.yelp.reviews(...)` | `POST /v1/yelp/reviews` |
139
+ | `client.tripadvisor.search(...)` | `POST /v1/tripadvisor/search` |
140
+ | `client.tripadvisor.place(...)` | `POST /v1/tripadvisor/place` |
141
+ | `client.tripadvisor.reviews(...)` | `POST /v1/tripadvisor/reviews` |
142
+
143
+ `client.bing` and `client.microsoft` are the same namespace. The API paths use `microsoft`.
144
+
145
+ Parameter names match the [API reference](https://www.prismcrawl.com/docs) exactly. Your editor shows each parameter's type and description.
146
+
147
+ ```python
148
+ places = client.google.maps.search(
149
+ query="coffee shop",
150
+ coordinates={"latitude": 30.2672, "longitude": -97.7431},
151
+ zoom=14,
152
+ )
153
+
154
+ reviews = client.google.maps.reviews(id="ChIJ...", limit=20)
155
+
156
+ products = client.amazon.search(query="espresso machine")
157
+ ```
158
+
159
+ ## AI answers
160
+
161
+ Google AI Overviews and Bing's AI overview come back in `serp_features` with type `ai_summary`. For Google's AI Mode, pass `udm=50`:
162
+
163
+ ```python
164
+ response = client.google.search(query="compare electric cars for a family", udm=50)
165
+
166
+ data = response["data"]
167
+ if data["format"] == "json":
168
+ for feature in data["content"]["serp_features"]:
169
+ if feature["type"] == "ai_summary":
170
+ print(feature)
171
+ ```
172
+
173
+ ## Pagination
174
+
175
+ Paginated endpoints have a `.pages()` iterator that takes the same parameters. It follows `next_page_token` (or `page`) until `has_next_page` is false.
176
+
177
+ ```python
178
+ for page in client.yelp.reviews.pages(id="halcyon-austin-2", max_pages=5):
179
+ for review in page["data"]["content"]["results"]:
180
+ print(review["rating"], review["text"][:80])
181
+ ```
182
+
183
+ Each page is a separate request and uses one credit. Use `max_pages` to cap spending.
184
+
185
+ ## Request history
186
+
187
+ Every response includes a `request_id`. Fetch a previous request with `.get()` on the endpoint that made it:
188
+
189
+ ```python
190
+ response = client.google.search(query="best espresso machines")
191
+ request_id = response["request_id"]
192
+
193
+ metadata = client.google.search.get(request_id)
194
+ archived = client.google.search.get(request_id, artifact="json") # parsed response
195
+ source = client.google.search.get(request_id, artifact="html") # source HTML, as str
196
+ ```
197
+
198
+ A new request can take a few seconds to appear in history. Until then, `.get()` raises `NotFoundError`.
199
+
200
+ Requests made with `zero_trace=True` aren't archived. For those, `.get()` returns only the status code and whether a credit was charged.
201
+
202
+ ## Source HTML
203
+
204
+ Pass `html=True` to get the provider's original page instead of parsed JSON. The API returns it as Base64-encoded Brotli, and `decode_html` converts it back to a string:
205
+
206
+ ```bash
207
+ pip install "prismcrawl[html]"
208
+ ```
209
+
210
+ ```python
211
+ from prismcrawl import decode_html
212
+
213
+ response = client.google.search(query="best espresso machines", html=True)
214
+ html = decode_html(response)
215
+ ```
216
+
217
+ ## Async
218
+
219
+ `AsyncPrismCrawl` has the same interface, with `await` in front of each call:
220
+
221
+ ```python
222
+ import asyncio
223
+ from prismcrawl import AsyncPrismCrawl
224
+
225
+
226
+ async def main() -> None:
227
+ async with AsyncPrismCrawl() as client:
228
+ google, bing = await asyncio.gather(
229
+ client.google.search(query="best espresso machines"),
230
+ client.bing.search(query="best espresso machines"),
231
+ )
232
+ async for page in client.tripadvisor.reviews.pages(id="...", max_pages=3):
233
+ ...
234
+
235
+
236
+ asyncio.run(main())
237
+ ```
238
+
239
+ ## Errors
240
+
241
+ Every exception inherits from `prismcrawl.PrismCrawlError`. API errors carry the status code, the error `code`, and the `request_id` to give support.
242
+
243
+ ```python
244
+ import prismcrawl
245
+
246
+ try:
247
+ client.google.search(query="best espresso machines")
248
+ except prismcrawl.RateLimitError as error:
249
+ print("Rate limited until", error.reset_at)
250
+ except prismcrawl.InsufficientCreditsError:
251
+ print("Out of credits")
252
+ except prismcrawl.APIStatusError as error:
253
+ print(error.status_code, error.code, error.message, error.request_id)
254
+ except prismcrawl.APIConnectionError:
255
+ print("Could not reach PrismCrawl")
256
+ ```
257
+
258
+ | Status | Exception |
259
+ |---|---|
260
+ | 400 | `BadRequestError` |
261
+ | 401 | `AuthenticationError` |
262
+ | 402 | `InsufficientCreditsError` |
263
+ | 404 | `NotFoundError` |
264
+ | 413 | `PayloadTooLargeError` |
265
+ | 429 | `RateLimitError` |
266
+ | 5xx | `InternalServerError` |
267
+ | other | `APIStatusError` |
268
+ | no response | `APIConnectionError`, `APITimeoutError` |
269
+
270
+ Failed requests don't use credits.
271
+
272
+ ## Retries and timeouts
273
+
274
+ The client retries up to 2 times, with exponential backoff, on:
275
+
276
+ - 429 responses, waiting until the limit resets if that's within 30 seconds
277
+ - 5xx responses
278
+ - connection failures
279
+
280
+ It never retries a search after the request was sent and the connection dropped, because the search may have completed and used a credit.
281
+
282
+ ```python
283
+ client = PrismCrawl(max_retries=5, timeout=60.0)
284
+
285
+ # Per-request timeout
286
+ client.google.search(query="...", timeout=10.0)
287
+ ```
288
+
289
+ The default timeout is 120 seconds.
290
+
291
+ ## Configuration
292
+
293
+ ```python
294
+ import httpx
295
+ from prismcrawl import PrismCrawl
296
+
297
+ client = PrismCrawl(
298
+ api_key="YOUR_API_KEY",
299
+ base_url="https://api.prismcrawl.com", # or PRISMCRAWL_BASE_URL
300
+ timeout=120.0,
301
+ max_retries=2,
302
+ default_headers={"x-my-header": "value"},
303
+ http_client=httpx.Client(proxy="http://localhost:8080"),
304
+ )
305
+ ```
306
+
307
+ If the API adds a parameter before this SDK does, pass it with `extra_body`:
308
+
309
+ ```python
310
+ client.google.search(query="...", extra_body={"new_param": True})
311
+ ```
312
+
313
+ ## Types
314
+
315
+ Responses are plain `dict`s. `prismcrawl.types` has a `TypedDict` for every request and response, so editors and type checkers know their shape:
316
+
317
+ ```python
318
+ from prismcrawl.types import GoogleJsonSearchResponse, SearchResult
319
+ ```
320
+
321
+ ## Pricing
322
+
323
+ Each successful request uses one PrismCrawl credit. Failed requests are free. Fetching another page is a separate request and uses a credit, including each page from `.pages()`.
324
+
325
+ - 100 free credits for new accounts
326
+ - Prepaid credit packages from $5, with no subscription
327
+ - As low as $0.15 per 1,000 successful requests at volume, 100x cheaper than SerpApi
328
+ - Credits are valid for 90 days
329
+
330
+ See [prismcrawl.com](https://www.prismcrawl.com) for current pricing.
331
+
332
+ ## Development
333
+
334
+ The endpoint classes and types come from the API's OpenAPI spec. To regenerate them:
335
+
336
+ ```bash
337
+ python scripts/generate.py --fetch # download the latest spec, then regenerate
338
+ python scripts/generate.py # regenerate from openapi.json
339
+ ```
340
+
341
+ Run the checks:
342
+
343
+ ```bash
344
+ python -m venv .venv && source .venv/bin/activate
345
+ pip install -e . pytest mypy ruff brotli
346
+ pytest && mypy && ruff check . && ruff format --check .
347
+ ```
348
+
349
+ ## Resources
350
+
351
+ - [PrismCrawl](https://www.prismcrawl.com): sign up, create API keys, and view your request history
352
+ - [API reference](https://www.prismcrawl.com/docs): every endpoint and parameter
353
+ - [Examples](https://github.com/prismcrawl/prismcrawl-python/tree/main/examples): runnable scripts for common tasks
354
+ - [TypeScript SDK](https://github.com/prismcrawl/prismcrawl-node)
355
+ - [MCP server](https://www.prismcrawl.com/mcp): connect Claude, Cursor, and other AI assistants to PrismCrawl ([GitHub](https://github.com/prismcrawl/prismcrawl-mcp))
356
+
357
+ ## Support
358
+
359
+ Email support@prismcrawl.com. To report a bug in this SDK, [open an issue](https://github.com/prismcrawl/prismcrawl-python/issues).
360
+
361
+ ## License
362
+
363
+ MIT