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

Next steps

API Reference — Full endpoint documentation
Back to Quickstart overview

Documentation Index

​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