Skip to content

Commit 4507eec

Browse files
VinciGit00VinciGit00
committed
docs: expand v1 to v2 transition guide with method mapping and examples
Made-with: Cursor
1 parent 1035719 commit 4507eec

File tree

1 file changed

+158
-4
lines changed

1 file changed

+158
-4
lines changed

‎transition-from-v1-to-v2.mdx‎

Lines changed: 158 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,24 +9,178 @@ If you are coming from the legacy v1 docs, use this page as your migration check
99

1010
Before anything else, log in to the dashboard at [scrapegraphai.com/login](https://scrapegraphai.com/login).
1111

12-
## What Changed in v2
12+
## What changed at a glance
13+
14+
| Area | v1 (before) | v2 (now) |
15+
|------|-------------|----------|
16+
| **REST paths** | `/v1/smartscraper`, `/v1/searchscraper`, `/v1/markdownify`, `/v1/crawl`, … | `/api/v2/extract`, `/api/v2/search`, `/api/v2/scrape`, `/api/v2/crawl`, `/api/v2/monitor`, … (see [Extract](/services/extract), [Search](/services/search), [Scrape](/services/scrape), [Crawl](/services/crawl)) |
17+
| **Python client** | `Client` with flat methods like `smartscraper()`, `searchscraper()` | Same `Client`, but **`extract()`**, **`search()`**, **`scrape()`**, and **namespaced** APIs: `crawl.start()`, `monitor.create()`, … |
18+
| **JavaScript** | Standalone functions: `smartScraper(apiKey, { ... })` | **Factory client**: `scrapegraphai({ apiKey })` then `sgai.extract()`, `sgai.search()`, … |
19+
| **Parameters** | Many top-level flags (`stealth`, `headers`, `mock`, …) on each call | Shared **`FetchConfig`** and **`LlmConfig`** objects (Python: `fetch_config` / `llm_config`; JS: `fetchConfig` / `llmConfig`) |
20+
| **Naming** | `website_url`, `user_prompt`, snake_case in Python | **`url`** and **`prompt`** for extract/search; JS uses **camelCase** everywhere |
21+
| **Errors (JS)** | Often returned as `{ status: 'error', error }` | Methods **throw** on failure; success is `{ data, requestId }` |
22+
23+
## Method-by-method migration
24+
25+
Use this table to map old entry points to new ones. Details and examples follow below.
26+
27+
| v1 | v2 | Notes |
28+
|----|-----|------|
29+
| `smartscraper` / `smartScraper` | **`extract`** | Same job: structured extraction from a URL. Rename params and pass extra fetch/LLM options via config objects. |
30+
| `searchscraper` / `searchScraper` | **`search`** | Web search + extraction; use `query` (or positional string in JS). |
31+
| `markdownify` | **`scrape`** with `format="markdown"` (Python) or `format: "markdown"` (JS) | HTML → markdown and related “raw page” outputs live under **`scrape`**. |
32+
| `crawl` (single start call) | **`crawl.start`**, then **`crawl.status`**, **`crawl.stop`**, **`crawl.resume`** | Crawl is explicitly async: you poll or track job id. |
33+
| Monitors (if you used them) | **`monitor.create`**, **`monitor.list`**, **`monitor.get`**, pause/resume/delete | Same product, namespaced API. |
34+
| `sitemap` | **Removed from v2 SDKs** | Discover URLs with **`crawl.start`** and URL patterns, or call the REST sitemap endpoint if your integration still requires it—see [Sitemap](/services/sitemap) and SDK release notes. |
35+
| `agenticscraper` | **Removed** | Use **`extract`** with `FetchConfig` (e.g. `render_js`, `wait_ms`, `stealth`) for hard pages, or **`crawl.start`** for multi-page flows. |
36+
| `healthz` / `checkHealth`, `feedback`, built-in mock helpers | **Removed or changed** | Use **`credits`**, **`history`**, and dashboard features; check the SDK migration guides for replacements. |
37+
38+
## Code-level transition
39+
40+
### 1. SmartScraper → `extract`
41+
42+
**Before (v1):** `website_url` + `user_prompt`, optional flags on the same object.
43+
44+
**After (v2):** `url` + `prompt`; move fetch-related flags into `FetchConfig` / `fetchConfig`.
45+
46+
<CodeGroup>
47+
48+
```python Python (v1)
49+
from scrapegraph_py import Client
50+
51+
client = Client(api_key="your-api-key")
52+
response = client.smartscraper(
53+
website_url="https://example.com",
54+
user_prompt="Extract the title and price",
55+
stealth=True,
56+
)
57+
```
58+
59+
```python Python (v2)
60+
from scrapegraph_py import Client, FetchConfig
61+
62+
client = Client(api_key="your-api-key")
63+
response = client.extract(
64+
url="https://example.com",
65+
prompt="Extract the title and price",
66+
fetch_config=FetchConfig(stealth=True),
67+
)
68+
```
69+
70+
```javascript JavaScript (v1)
71+
import { smartScraper } from "scrapegraph-js";
72+
73+
const response = await smartScraper(apiKey, {
74+
website_url: "https://example.com",
75+
user_prompt: "Extract the title and price",
76+
stealth: true,
77+
});
78+
```
79+
80+
```javascript JavaScript (v2)
81+
import { scrapegraphai } from "scrapegraph-js";
82+
83+
const sgai = scrapegraphai({ apiKey });
84+
const { data, requestId } = await sgai.extract("https://example.com", {
85+
prompt: "Extract the title and price",
86+
fetchConfig: { stealth: true },
87+
});
88+
```
89+
90+
</CodeGroup>
91+
92+
### 2. SearchScraper → `search`
93+
94+
**Before:** `searchscraper` / `searchScraper` with a prompt-style query.
95+
96+
**After:** `search` with `query` (Python keyword argument; JS first argument is the query string).
97+
98+
<CodeGroup>
99+
100+
```python Python (v2)
101+
response = client.search(
102+
query="Latest pricing for product X",
103+
num_results=5,
104+
)
105+
```
106+
107+
```javascript JavaScript (v2)
108+
const { data } = await sgai.search("Latest pricing for product X", {
109+
numResults: 5,
110+
});
111+
```
112+
113+
</CodeGroup>
114+
115+
### 3. Markdownify → `scrape`
116+
117+
**Before:** `markdownify(url)`.
118+
119+
**After:** `scrape(url, format="markdown")` (Python) or `scrape(url, { format: "markdown" })` (JS).
120+
121+
### 4. Crawl jobs
122+
123+
**Before:** One-shot `crawl(...)` style usage depending on SDK version.
124+
125+
**After:** Start a job, then poll or webhook as documented:
126+
127+
<CodeGroup>
128+
129+
```python Python (v2)
130+
job = client.crawl.start(
131+
url="https://example.com",
132+
depth=2,
133+
include_patterns=["/blog/*"],
134+
exclude_patterns=["/admin/*"],
135+
)
136+
status = client.crawl.status(job["id"])
137+
```
138+
139+
```javascript JavaScript (v2)
140+
const job = await sgai.crawl.start("https://example.com", {
141+
maxDepth: 2,
142+
includePatterns: ["/blog/*"],
143+
excludePatterns: ["/admin/*"],
144+
});
145+
const status = await sgai.crawl.status(job.data.id);
146+
```
147+
148+
</CodeGroup>
149+
150+
### 5. REST calls
151+
152+
If you call the API with `curl` or a generic HTTP client:
153+
154+
- Use the v2 host and path pattern: **`https://api.scrapegraphai.com/api/v2/<endpoint>`** (e.g. `/api/v2/extract`, `/api/v2/monitor`).
155+
- Replace JSON fields to match v2 bodies (e.g. `url` and `prompt` instead of `website_url` and `user_prompt` on extract).
156+
- Keep using the **`SGAI-APIKEY`** header unless the endpoint docs specify otherwise.
157+
158+
Exact paths and payloads are listed under each service (for example [Extract](/services/extract)) and in the [API reference](/api-reference/introduction).
159+
160+
## What else changed in v2 (docs & product)
13161

14162
- Unified and clearer API documentation
15163
- Updated service pages and endpoint organization
16164
- New guides for MCP server and SDK usage
17165

18-
## Recommended Path
166+
## Recommended path
19167

20168
1. Log in at [scrapegraphai.com/login](https://scrapegraphai.com/login)
21169
2. Start from [Introduction](/introduction)
22170
3. Follow [Installation](/install)
171+
4. Upgrade packages: `pip install -U scrapegraph-py` / `npm i scrapegraph-js@latest` (Node **≥ 22** for JS v2)
23172

24-
## SDK Migration Guides
173+
## SDK migration guides (detailed changelogs)
25174

26175
- [Python SDK Migration Guide](https://github.com/ScrapeGraphAI/scrapegraph-py/blob/main/MIGRATION_V2.md)
27176
- [JavaScript SDK Migration Guide](https://github.com/ScrapeGraphAI/scrapegraph-js/blob/main/MIGRATION.md)
28177

29-
## Legacy v1 Docs
178+
Full method documentation:
179+
180+
- [Python SDK](/sdks/python)
181+
- [JavaScript SDK](/sdks/javascript)
182+
183+
## Legacy v1 docs
30184

31185
You can still access v1 documentation here:
32186

0 commit comments

Comments
 (0)