Skip to main content
Install the Nimble Go library to interact with the Nimble API from your Go applications. Built with idiomatic Go patterns, full context support, and automatic retries.

​
Installation

go get github.com/Nimbleway/nimble-go@latest'
Requires Go 1.22+. Set your API key via the NIMBLE_API_KEY environment variable or pass it directly using option.WithAPIKey().

​
Setup

Import the package and initialize the client:
Go
package main

import (
    "context"
    "fmt"
    "os"

    nimble "github.com/Nimbleway/nimble-go"
    "github.com/Nimbleway/nimble-go/option"
)

func main() {
    client := nimble.NewClient(
        option.WithAPIKey(os.Getenv("NIMBLE_API_KEY")),
    )

    _ = client
    fmt.Println("Client ready")
}

​
Quick Start

Extract content from a URL:
Go
package main

import (
    "context"
    "fmt"
    "os"

    nimble "github.com/Nimbleway/nimble-go"
    "github.com/Nimbleway/nimble-go/option"
)

func main() {
    client := nimble.NewClient(
        option.WithAPIKey(os.Getenv("NIMBLE_API_KEY")),
    )

    result, err := client.Extract(context.TODO(), nimble.ExtractParams{
        URL: "https://www.example.com",
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("Task ID: %s\n", result.TaskID)
}

​
Core Methods

​
Extract

Get clean HTML, markdown, or structured data from any URL:
Go
result, err := client.Extract(context.TODO(), nimble.ExtractParams{
    URL:    "https://www.example.com",
    Render: nimble.Bool(true),
})
if err != nil {
    panic(err)
}
fmt.Println(result.TaskID)
Optional fields are wrapped in param.Opt[T]. Use the provided constructors — nimble.Bool(), nimble.String(), nimble.Int() — to set them.
Perform real-time web searches:
Go
result, err := client.Search(context.TODO(), nimble.SearchParams{
    Query:   "best web scraping tools",
    Country: nimble.String("US"),
})
if err != nil {
    panic(err)
}
fmt.Println(result)

​
Map

Discover all URLs within a domain or sitemap:
Go
result, err := client.Map(context.TODO(), nimble.MapParams{
    URL:     "https://www.example.com",
    Sitemap: nimble.String("only"),
})
if err != nil {
    panic(err)
}
fmt.Println(result)

​
Crawl

Recursively crawl and extract an entire website:
Go
result, err := client.Crawl.Run(context.TODO(), nimble.CrawlRunParams{
    URL:   "https://www.example.com",
    Limit: nimble.Int(100),
})
if err != nil {
    panic(err)
}
fmt.Println(result)

​
Agents

Run pre-built agents for structured data from popular platforms:
Go
result, err := client.Agent.Run(context.TODO(), nimble.AgentRunParams{
    Agent: "amazon_pdp",
    Params: map[string]interface{}{
        "asin": "B08N5WRWNW",
    },
})
if err != nil {
    panic(err)
}
fmt.Println(result)
Browse the full agent catalog in the Agent Gallery.

​
Error Handling

Check err != nil for any failed request. Use errors.As to inspect typed API errors:
Go
import (
    "errors"
    "fmt"

    nimble "github.com/Nimbleway/nimble-go"
)

result, err := client.Extract(context.TODO(), nimble.ExtractParams{
    URL: "https://www.example.com",
})
if err != nil {
    var apiErr *nimble.Error
    if errors.As(err, &apiErr) {
        fmt.Printf("API error — status: %d, message: %s\n",
            apiErr.StatusCode, apiErr.Message)
    }
    panic(err)
}
The *nimble.Error type exposes:
  • StatusCode int — HTTP status code
  • Message string — Human-readable error description

​
Configuration

​
Retries

The SDK retries automatically on connection errors, timeouts, and server failures (2 retries by default):
Go
// Configure globally
client := nimble.NewClient(
    option.WithAPIKey(os.Getenv("NIMBLE_API_KEY")),
    option.WithMaxRetries(3),
)

// Disable retries for a specific request
result, err := client.Extract(context.TODO(), nimble.ExtractParams{
    URL: "https://www.example.com",
}, option.WithMaxRetries(0))

​
Timeouts

Use Go’s standard context package for request timeouts:
Go
import (
    "context"
    "time"
)

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

result, err := client.Extract(ctx, nimble.ExtractParams{
    URL: "https://www.example.com",
})
Or set a per-request timeout directly:
Go
result, err := client.Extract(context.TODO(), nimble.ExtractParams{
    URL: "https://www.example.com",
}, option.WithRequestTimeout(30*time.Second))

​
Advanced

​
Raw Response Access

Capture the raw HTTP response alongside the parsed result:
Go
import "net/http"

var rawResponse *http.Response

result, err := client.Extract(context.TODO(), nimble.ExtractParams{
    URL: "https://www.example.com",
}, option.WithResponseInto(&rawResponse))
if err != nil {
    panic(err)
}

fmt.Println(rawResponse.Header.Get("x-request-id"))
fmt.Println(result.TaskID)

​
Custom Request Options

Attach additional headers or query parameters to any request:
Go
result, err := client.Extract(context.TODO(), nimble.ExtractParams{
    URL: "https://www.example.com",
},
    option.WithHeader("X-Custom-Header", "value"),
    option.WithQueryParam("debug", "true"),
)

​
Next Steps

API Reference

Full REST API documentation for all endpoints

Extract

Rendering, formats, stealth mode, and more

Search

Real-time web search with structured results

Agents

Pre-built extraction agents for popular platforms