Go - Nimble Docs

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:

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:

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:

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.

Search

Perform real-time web searches:

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:

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:

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:

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:

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):

// 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:

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:

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:

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:

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

​Installation

​Setup

​Quick Start

​Core Methods

​Extract

​Search

​Map

​Crawl

​Agents

​Error Handling

​Configuration

​Retries

​Timeouts

​Advanced

​Raw Response Access

​Custom Request Options

​Next Steps

API Reference

Extract

Search

Agents

Installation

Setup

Quick Start

Core Methods

Extract

Search

Map

Crawl

Agents

Error Handling

Configuration

Retries

Timeouts

Advanced

Raw Response Access

Custom Request Options

Next Steps