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 (
    "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.Run(context.TODO(), nimble.ExtractRunParams{
        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.Run(context.TODO(), nimble.ExtractRunParams{
    URL:    "https://www.example.com",
    Render: nimble.ExtractRunParamsRenderUnion{OfBool: 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.MapParamsSitemapOnly,
})
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)

Extract Template

Run pre-built extraction templates for structured data from popular platforms:

result, err := client.Extract.Templates.Run(context.TODO(), nimble.ExtractTemplateRunParams{
    Template: "amazon_pdp",
    Params: map[string]any{
        "asin": "B08N5WRWNW",
    },
})
if err != nil {
    panic(err)
}
fmt.Println(result.Data.Parsing)

Browse the full template catalog with client.Extract.Templates.List().

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.Run(context.TODO(), nimble.ExtractRunParams{
    URL: "https://www.example.com",
})
if err != nil {
    var apiErr *nimble.Error
    if errors.As(err, &apiErr) {
        fmt.Printf("API error — status: %d: %s\n",
            apiErr.StatusCode, apiErr.Error())
    }
    panic(err)
}

The *nimble.Error type exposes:

StatusCode int — HTTP status code
Error() string — Human-readable error description
Request / Response — the underlying HTTP exchange

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.Run(context.TODO(), nimble.ExtractRunParams{
    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.Run(ctx, nimble.ExtractRunParams{
    URL: "https://www.example.com",
})

Or set a per-request timeout directly:

result, err := client.Extract.Run(context.TODO(), nimble.ExtractRunParams{
    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.Run(context.TODO(), nimble.ExtractRunParams{
    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.Run(context.TODO(), nimble.ExtractRunParams{
    URL: "https://www.example.com",
},
    option.WithHeader("X-Custom-Header", "value"),
    option.WithQuery("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

Templates

Pre-built extraction templates for popular platforms

Getting Started

Search

Web Search Agent

Extraction Tools

Extract Template

Extract Jobs

Guides

SDKs

Admin

Proxy

Go

Installation

Setup

Quick Start

Core Methods

Extract

Search

Map

Crawl

Extract Template

Error Handling

Configuration

Retries

Timeouts

Advanced

Raw Response Access

Custom Request Options

Next Steps

API Reference

Extract

Search

Templates

​Installation

​Setup

​Quick Start

​Core Methods

​Extract

​Search

​Map

​Crawl

​Extract Template

​Error Handling

​Configuration

​Retries

​Timeouts

​Advanced

​Raw Response Access

​Custom Request Options

​Next Steps

API Reference

Extract

Search

Templates

Installation

Setup

Quick Start

Core Methods

Extract

Search

Map

Crawl

Extract Template

Error Handling

Configuration

Retries

Timeouts

Advanced

Raw Response Access

Custom Request Options

Next Steps