Masukkan satu URL, dapatkan data terstruktur yang rapi

Scraping

Yozh Scraper menampilkan URL apa pun di browser Playwright yang sesungguhnya dan mengembalikan persis apa yang Anda minta — bidang yang diekstraksi, HTML mentah, atau tangkapan layar halaman penuh. Setiap proses pengikisan merupakan tugas asinkron: kirimkan URL, periksa status tugas, dan ambil hasilnya. Proksi, mode tersembunyi, preset, dan sesi terotentikasi semuanya didukung sepenuhnya.

• Render browser sesungguhnya — Playwright menampilkan halaman yang dibuat dengan JS; beralih render untuk HTML statis.
• Ekstraksi terstruktur — Aturan bidang CSS atau XPath menghasilkan objek yang rapi data , jauh lebih efisien daripada mengunduh dan mengurai HTML mentah sendiri.
• Proksi bawaan — CyberYozh (residensial / LTE seluler / pusat data), dilengkapi dengan penargetan GEO dan tanpa pencarian ID pool.
• Mode Stealth secara default — tambalan playwright-stealth (navigator.webdriver, sidik jari WebGL/Canvas, runtime Chrome) untuk mengurangi deteksi bot.
• Preset — mengekstrak data dari Amazon / Google / eBay / Walmart / YouTube / LinkedIn berdasarkan nama, dengan fitur pemulihan otomatis LLM (opsional).
• Sesi — sesi terotentikasi yang dikelola oleh server untuk target yang telah masuk, dan dapat digunakan kembali di seluruh proses pengumpulan data.

Mulai cepat

Pengikis itu muncul dari akarnya docker-compose.yml (bersamaan dengan crawler):

cp .env.example .env          # set CYBERYOZH_API_KEY if using proxies
docker compose up --build
# scraper → http://localhost:8000
# crawler → http://localhost:8001

Pastikan sudah aktif:

curl http://localhost:8000/api/v1/health
# {"status":"ok","workers":2}

Penggunaan dasar

Setiap titik akhir scrape membuat tugas latar belakang dan mengembalikan sebuah job_id. Periksa status pekerjaan tersebut, lalu ambil hasilnya.

curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://example.com", "proxy_type": "none" }'
# → { "job_id": "req_abc123" }

curl http://localhost:8000/api/v1/scrape/req_abc123          # status
curl http://localhost:8000/api/v1/scrape/req_abc123/results  # results

Hasil akhir berisi metadata serta apa pun yang Anda minta (data, raw_html, screenshot_base64):

{
  "job_id": "req_abc123",
  "status": "done",
  "total": 1, "done": 1,
  "results": [
    {
      "request_id": "req_abc123",
      "took_ms": 1234,
      "meta": { "url": "https://example.com", "final_url": "https://example.com/",
                "status_code": 200, "device": "desktop", "proxy_type": "none", "retries": 0 },
      "data": null, "raw_html": null, "screenshot_base64": null, "warnings": []
    }
  ]
}

Mengekstrak data

Terapkan sebuah extract aturan, dan responsnya mencakup sebuah data objek yang diindeks berdasarkan nama bidang Anda — jauh lebih efisien daripada mengunduh raw_html dan menganalisisnya sendiri. Aturan-aturan tersebut css atau xpath.

curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{
    "url": "https://example.com",
    "extract": {
      "type": "css",
      "fields": {
        "title": { "selector": "h1", "attr": "text", "required": true }
      }
    }
  }'
# result → { "data": { "title": "Example Domain" } }

Setiap kolom merupakan sebuah aturan:

Gunakan "type": "xpath" bersama selektor XPath (misalnya //h1) untuk bentuk yang sama.

Tangkapan layar & kode HTML mentah

Atur screenshot: true untuk gambar PNG satu halaman penuh (dalam format base64 screenshot_base64), atau raw_html: true untuk mendapatkan HTML lengkap setelah dirender dalam raw_html.

curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://example.com", "screenshot": true, "raw_html": true }'

Proxy

Untuk proses scraping yang andal, proxy sangat penting — kebanyakan situs modern memblokir permintaan langsung. Yozh terintegrasi dengan Layanan Proxy CyberYozh; atur proxy_type pada setiap permintaan.

Pilih lokasi dengan proxy_geo (country_code / region / city). Temukan apa yang telah Anda beli tanpa perlu mencari ID kolam:

curl "http://localhost:8000/api/v1/proxies/available?proxy_type=res_rotating"
curl "http://localhost:8000/api/v1/proxies/countries"

Preset

Sebuah preset menggabungkan profil permintaan + templat URL + resep penguraian, sehingga Anda dapat mengekstrak data dari sebuah situs berdasarkan namanya, alih-alih menyusun permintaan secara manual. Tersedia preset bawaan untuk Amazon, Google, eBay, Walmart, YouTube, dan LinkedIn; Anda juga dapat membuat preset sendiri (menggunakan CSS/XPath deterministik atau yang dihasilkan oleh AI).

curl -X POST http://localhost:8000/api/v1/scrape/preset/page 
  -H "Content-Type: application/json" 
  -d '{
    "source": "amazon_product",
    "preset_params": { "asin": "B08N5WRWNW" },
    "locale": "us",
    "llm": { "model": "openai/gpt-5.4-mini" }
  }'
# → { "job_id": "..." }  then GET /api/v1/scrape/<job_id>/results

Kelola pengaturan default melalui GET /api/v1/presets, GET /api/v1/presets/{name}, dan POST /api/v1/presets (nama preset pengguna harus diawali dengan user_).

Sesi

Sesi terotentikasi yang dikelola server: buat satu sesi, masuk sekali, lalu serahkan session_id ke proses pengikisan mana pun sehingga halaman diambil dengan cookie yang tersimpan + status penyimpanan. Diperlukan untuk target yang sudah masuk seperti linkedin_profile pengaturan awal.

1. POST /api/v1/sessions — buat. Pin device / proxy_type / proxy_geo dan TTL. Mengembalikan { session_id, expires_at }.
2. POST /api/v1/sessions/{id}/login — menjalankan ulang skrip login deklaratif dengan creds di bagian isi: { script, creds }.
3. POST /api/v1/scrape/page bersama session_id set — pengikisan yang terotentikasi.
4. DELETE /api/v1/sessions/{id} — bersihkan.

# 1. create  →  {"session_id":"sess_...","expires_at":...}
curl -X POST http://localhost:8000/api/v1/sessions 
  -H "Content-Type: application/json" 
  -d '{ "device": "desktop", "proxy_type": "res_rotating" }'

# 2. log in (declarative DSL + creds)
curl -X POST http://localhost:8000/api/v1/sessions/sess_.../login 
  -H "Content-Type: application/json" 
  -d '{ "script": { "steps": [ {"op":"goto","url":"https://site/login"} ] },
        "creds": { "username": "...", "password": "..." } }'

# 3. scrape with the session
curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://site/secure", "session_id": "sess_...", "raw_html": true }'

Pengambilan data secara batch

Kirimkan banyak halaman dalam satu tugas dengan POST /api/v1/scrape/pages — setiap entri merupakan permintaan pengambilan data lengkap. Periksa status dan ambil hasil melalui titik akhir tugas yang sama.

curl -X POST http://localhost:8000/api/v1/scrape/pages 
  -H "Content-Type: application/json" 
  -d '{
    "pages": [
      { "url": "https://example.com", "proxy_type": "none" },
      { "url": "https://example.org", "proxy_type": "none" }
    ]
  }'

MCP

Scraper ini menghosting titik akhir Model Context Protocol di /mcp (Streamable HTTP). Arahkan Claude atau Cursor ke sana, dan alat-alat tersebut akan muncul secara otomatis:

• run_scrape_page
• run_scrape_pages
• get_job_status
• get_job_result
• cancel_scrape_job
• health

"yozh-scraper": {
  "type": "http",
  "url": "http://localhost:8000/mcp"
}

Lalu cukup tanyakan: "Lakukan scraping pada https://example.com dan beritahu saya apa yang ada di halaman tersebut." Endpoint yang sama dapat digunakan baik dari agen LangChain maupun node n8n MCP Client Tool.

Panduan Konfigurasi

Permintaan — ScrapeRequest (terpilih)

Referensi API

Rincian penting