Go - Geekflare

No SDK is needed for Go. The standard net/http and encoding/json packages are all you need. This guide builds a reusable client struct that you can drop into any Go project.

Prerequisites

Go 1.21+
A Geekflare API key — get one free

Set your API key

.env

GEEKFLARE_API_KEY=your_api_key_here

Load it with godotenv:

go get github.com/joho/godotenv

import "github.com/joho/godotenv"

func init() {
    if err := godotenv.Load(); err != nil {
        log.Println("No .env file found, reading from environment")
    }
}

apiKey := os.Getenv("GEEKFLARE_API_KEY")
if apiKey == "" {
    log.Fatal("GEEKFLARE_API_KEY is not set")
}

Add .env to .gitignore. In production, inject the key directly as an environment variable.

Reusable client

internal/geekflare/client.go

package geekflare

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "time"
)

const baseURL = "https://api.geekflare.com"

// Client is a simple Geekflare API client.
type Client struct {
    apiKey     string
    httpClient *http.Client
}

// New creates a new Geekflare Client.
func New(apiKey string) *Client {
    return &Client{
        apiKey: apiKey,
        httpClient: &http.Client{
            Timeout: 30 * time.Second,
        },
    }
}

// APIError represents a non-2xx response from the Geekflare API.
type APIError struct {
    APICode int    `json:"apiCode"`
    Message string `json:"message"`
}

func (e *APIError) Error() string {
    return fmt.Sprintf("geekflare API error [%d]: %s", e.APICode, e.Message)
}

// post sends a POST request and decodes the response into out.
func (c *Client) post(path string, body any, out any) error {
    b, err := json.Marshal(body)
    if err != nil {
        return fmt.Errorf("marshal request: %w", err)
    }

    req, err := http.NewRequest(http.MethodPost, baseURL+path, bytes.NewReader(b))
    if err != nil {
        return fmt.Errorf("create request: %w", err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-api-key", c.apiKey)

    resp, err := c.httpClient.Do(req)
    if err != nil {
        return fmt.Errorf("execute request: %w", err)
    }
    defer resp.Body.Close()

    data, err := io.ReadAll(resp.Body)
    if err != nil {
        return fmt.Errorf("read response: %w", err)
    }

    if resp.StatusCode != http.StatusOK {
        var apiErr APIError
        if jsonErr := json.Unmarshal(data, &apiErr); jsonErr != nil {
            return fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(data))
        }
        return &apiErr
    }

    return json.Unmarshal(data, out)
}

Web Scraping

Types

internal/geekflare/scrape.go

package geekflare

// WebScrapeRequest represents the request body for the webscraping endpoint.
type WebScrapeRequest struct {
    URL      string  `json:"url"`
    Device   string  `json:"device,omitempty"`
    RenderJS bool    `json:"renderJS,omitempty"`
    BlockAds bool    `json:"blockAds,omitempty"`
    Format   string  `json:"format,omitempty"`
    Stealth  bool    `json:"stealth,omitempty"`
    WaitTime float64 `json:"waitTime,omitempty"`
}

// WebScrapeResponse is the API response for the webscraping endpoint.
// Data is a URL pointing to the scraped output file.
type WebScrapeResponse struct {
    Timestamp int64  `json:"timestamp"`
    APIStatus string `json:"apiStatus"`
    APICode   int    `json:"apiCode"`
    Data      string `json:"data"`
}

// WebScrape scrapes a web page and returns its content.
func (c *Client) WebScrape(req WebScrapeRequest) (*WebScrapeResponse, error) {
    var out WebScrapeResponse
    if err := c.post("/webscraping", req, &out); err != nil {
        return nil, err
    }
    return &out, nil
}

Usage

cmd/scrape/main.go

package main

import (
    "fmt"
    "log"
    "os"

    "github.com/joho/godotenv"
    "yourmodule/internal/geekflare"
)

func main() {
    _ = godotenv.Load()

    client := geekflare.New(os.Getenv("GEEKFLARE_API_KEY"))

    result, err := client.WebScrape(geekflare.WebScrapeRequest{
        URL:      "https://toscrape.com/",
        Device:   "desktop",
        RenderJS: true,
        BlockAds: true,
        Format:   "html,markdown",
    })
    if err != nil {
        log.Fatal(err)
    }

    // result.Data is a URL to the scraped output file
    fmt.Println("Output file URL:", result.Data)
}

Search

Types

internal/geekflare/search.go

package geekflare

// SearchRequest represents the request body for the search endpoint.
type SearchRequest struct {
    Query          string   `json:"query"`
    Limit          int      `json:"limit,omitempty"`
    Location       string   `json:"location,omitempty"`
    Source         string   `json:"source,omitempty"`
    Time           string   `json:"time,omitempty"`
    Format         string   `json:"format,omitempty"`
    IncludeDomains []string `json:"includeDomains,omitempty"`
    ExcludeDomains []string `json:"excludeDomains,omitempty"`
}

// SearchResult is a single result in the search response.
type SearchResult struct {
    Title    string `json:"title"`
    URL      string `json:"url"`
    Snippet  string `json:"snippet"`
    Date     string `json:"date"`
    Position int    `json:"position"`
    Content  string `json:"content"`
}

// SearchResponse is the API response for the search endpoint.
type SearchResponse struct {
    Timestamp int64          `json:"timestamp"`
    APIStatus string         `json:"apiStatus"`
    APICode   int            `json:"apiCode"`
    Data      []SearchResult `json:"data"`
}

// Search performs a web search.
func (c *Client) Search(req SearchRequest) (*SearchResponse, error) {
    var out SearchResponse
    if err := c.post("/search", req, &out); err != nil {
        return nil, err
    }
    return &out, nil
}

Usage

cmd/search/main.go

package main

import (
    "fmt"
    "log"
    "os"

    "github.com/joho/godotenv"
    "yourmodule/internal/geekflare"
)

func main() {
    _ = godotenv.Load()

    client := geekflare.New(os.Getenv("GEEKFLARE_API_KEY"))

    result, err := client.Search(geekflare.SearchRequest{
        Query:    "best Go web frameworks",
        Limit:    10,
        Location: "us",
        Source:   "web",
        Time:     "m",
        Format:   "json",
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, item := range result.Data {
        fmt.Printf("%s\n  %s\n  %s\n\n", item.Title, item.URL, item.Snippet)
    }
}

Screenshot

Types

internal/geekflare/screenshot.go

package geekflare

// ScreenshotRequest represents the request body for the screenshot endpoint.
type ScreenshotRequest struct {
    URL            string `json:"url"`
    Type           string `json:"type,omitempty"`
    FullPage       bool   `json:"fullPage,omitempty"`
    Device         string `json:"device,omitempty"`
    ViewportWidth  int    `json:"viewportWidth,omitempty"`
    ViewportHeight int    `json:"viewportHeight,omitempty"`
    BlockAds       bool   `json:"blockAds,omitempty"`
    HideCookie     bool   `json:"hideCookie,omitempty"`
    Quality        int    `json:"quality,omitempty"`
    Delay          int    `json:"delay,omitempty"`
}

// ScreenshotResponse is the API response for the screenshot endpoint.
// Data is a direct URL string pointing to the captured screenshot image.
type ScreenshotResponse struct {
    Timestamp int64  `json:"timestamp"`
    APIStatus string `json:"apiStatus"`
    APICode   int    `json:"apiCode"`
    Data      string `json:"data"`
}

// Screenshot captures a screenshot of a URL.
func (c *Client) Screenshot(req ScreenshotRequest) (*ScreenshotResponse, error) {
    var out ScreenshotResponse
    if err := c.post("/screenshot", req, &out); err != nil {
        return nil, err
    }
    return &out, nil
}

Usage

cmd/screenshot/main.go

package main

import (
    "fmt"
    "log"
    "os"

    "github.com/joho/godotenv"
    "yourmodule/internal/geekflare"
)

func main() {
    _ = godotenv.Load()

    client := geekflare.New(os.Getenv("GEEKFLARE_API_KEY"))

    result, err := client.Screenshot(geekflare.ScreenshotRequest{
        URL:            "https://example.com",
        Type:           "png",
        FullPage:       true,
        Device:         "desktop",
        ViewportWidth:  1280,
        ViewportHeight: 800,
        BlockAds:       true,
        HideCookie:     true,
        Quality:        90,
    })
    if err != nil {
        log.Fatal(err)
    }

    // result.Data is the screenshot URL directly
    fmt.Println("Screenshot URL:", result.Data)
}

Error handling

The APIError type returned by the client carries the status code and message. Use errors.As to inspect it:

import (
    "errors"
    "log"

    "yourmodule/internal/geekflare"
)

result, err := client.WebScrape(geekflare.WebScrapeRequest{URL: "https://toscrape.com/"})
if err != nil {
    var apiErr *geekflare.APIError
    if errors.As(err, &apiErr) {
        switch apiErr.APICode {
        case 401:
            log.Fatal("Invalid or missing API key.")
        case 402:
            log.Fatal("API credits exhausted. Top up at dash.geekflare.com.")
        case 403:
            log.Fatal("Endpoint not available on your plan.")
        case 429:
            log.Println("Rate limit exceeded. Back off and retry.")
            // implement exponential backoff here
        default:
            log.Fatalf("API error [%d]: %s", apiErr.APICode, apiErr.Message)
        }
    }
    log.Fatal("Unexpected error:", err)
}

Common error codes

Code	Meaning
`401`	Missing or invalid `x-api-key`
`402`	API credits exhausted
`403`	Endpoint requires a higher plan
`404`	Wrong endpoint URL or HTTP method
`429`	Rate limit exceeded

See Rate Limit Exceeded and Credit Exhausted for strategies to handle these gracefully.

Next steps

API Reference — Full endpoint documentation
Back to Quickstart overview

Getting started

Quickstarts

Guides

MCP Server

Capabilities

Best Practices

Troubleshooting

Changelog

Go

Prerequisites

Set your API key

Reusable client

Web Scraping

Types

Usage

Search

Types

Usage

Screenshot

Types

Usage

Error handling

Common error codes

Next steps

​Prerequisites

​Set your API key

​Reusable client

​Web Scraping

​Types

​Usage

​Search

​Types

​Usage

​Screenshot

​Types

​Usage

​Error handling

​Common error codes

​Next steps

Prerequisites

Set your API key

Reusable client

Web Scraping

Types

Usage

Search

Types

Usage

Screenshot

Types

Usage

Error handling

Common error codes

Next steps