Scraper API Quick Start Guide

The Geonode Scraper API lets you send a webpage URL and get extracted page content back as Markdown or HTML. It handles proxy routing, geo-targeting, JavaScript rendering, and anti-bot handling for you, so you do not have to build a proxy pipeline or run your own browser infrastructure before you can start collecting page content.

Before You Start

You'll need a Geonode account and a Scraper API key. If you have not created an account yet, sign up from the Geonode dashboard first.

Once you're inside the dashboard:

• Open the Scraper API section.
• Create or copy your API key.
• Store the key somewhere safe.
• Do not expose the key in frontend code, public repositories, logs, screenshots, or support messages.

The examples in this guide use these two environment variables:

export SCRAPER_API_BASE_URL="https://scraper.geonode.io"
export GEONODE_SCRAPER_API_KEY="YOUR_API_KEY"

Make Your First Request

Start with a simple static page and request Markdown output. Markdown is usually the easiest format to inspect when you're testing the API for the first time.

curl -X POST "$SCRAPER_API_BASE_URL/v1/extract" \
  -H "X-Api-Key: $GEONODE_SCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "render_js": false,
    "processing_mode": "sync"
  }'

A successful synchronous request returns 200 with the extracted content, request metadata, and the number of requests charged.

{
  "data": {
    "html": null,
    "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples in documents...",
    "links": null
  },
  "metadata": {
    "url": "https://example.com",
    "render_js": false,
    "http_status": 200,
    "duration_ms": 1262,
    "retry_count": 0,
    "formats": ["markdown"],
    "proxy": {
      "country": null,
      "type": "residential"
    },
    "processing_mode": "sync",
    "headers": null
  },
  "tokens_charged": 1
}

The response body is always JSON. The extracted page content appears inside data.markdown or data.html, depending on the formats you request. The API response field is currently named tokens_charged, but in Scraper API billing language this means charged requests.

Request HTML Instead

If you need sanitized HTML instead of Markdown, set formats to ["html"].

curl -X POST "$SCRAPER_API_BASE_URL/v1/extract" \
  -H "X-Api-Key: $GEONODE_SCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["html"],
    "render_js": false,
    "processing_mode": "sync"
  }'

The response will include the extracted HTML in data.html. When you request only HTML, data.markdown is usually null.

Request Markdown and HTML Together

You can also request both formats in the same call.

curl -X POST "$SCRAPER_API_BASE_URL/v1/extract" \
  -H "X-Api-Key: $GEONODE_SCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown", "html"],
    "render_js": false,
    "processing_mode": "sync"
  }'

In this case, the response can include both data.markdown and data.html.

Use JavaScript Rendering

Some pages load their main content in the browser after the initial HTML response. For those pages, the non-rendered output may contain the page shell but miss the content you actually need.

Use render_js: true when the page depends on client-side rendering.

curl -X POST "$SCRAPER_API_BASE_URL/v1/extract" \
  -H "X-Api-Key: $GEONODE_SCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://quotes.toscrape.com/js/",
    "formats": ["markdown"],
    "render_js": true,
    "processing_mode": "sync"
  }'

JavaScript rendering does not cost extra requests. It can take longer than a normal extraction, so start with render_js: false and turn it on only when the returned content is incomplete.

Choose a Proxy Location

By default, the Scraper API uses residential proxy routing and auto-resolves a country from the target URL when possible. You can override the proxy country and proxy type with the proxy object.

curl -X POST "$SCRAPER_API_BASE_URL/v1/extract" \
  -H "X-Api-Key: $GEONODE_SCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "render_js": false,
    "processing_mode": "sync",
    "proxy": {
      "country": "US",
      "type": "residential"
    }
  }'

The country value must be a two-letter ISO country code such as US, GB, or DE. Supported proxy types are residential, datacenter, and mix.

Check Remaining Requests

You can check your remaining Scraper API requests in the Geonode dashboard. Open the Scraper API area in your account and review the request balance shown for your free, subscription, or Pay as you Go usage.

For free accounts, the monthly free request allowance renews every billing month and does not roll over. Paid subscription requests roll over to the next month, and Pay as you Go requests do not expire.

Next Steps

Now that you've made your first request, you can read the full API reference for request parameters, async jobs, batch extraction, crawl jobs, webhooks, error responses, and code examples.

Open the Scraper API Reference