socialapis

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 23, 2026 License: MIT Imports: 9 Imported by: 0

README

socialapis-go — Go SDK for Facebook + Instagram public data

Go Reference Go Report Card License Go

Idiomatic Go client for the socialapis.io REST API. Mirrors the Python and JavaScript SDKs — same 51 endpoints, same envelope handling, same migration aliases — but with Go conventions: context-aware methods, functional options, typed errors, zero external dependencies.

go get github.com/SocialAPIsHub/socialapis-go@latest

package main

import (
    "context"
    "fmt"
    "log"

    socialapis "github.com/SocialAPIsHub/socialapis-go"
)

func main() {
    fb, err := socialapis.NewFacebook("YOUR_API_TOKEN")
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()
    page, err := fb.GetPageInfo(ctx, "EngenSA", nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(page.Title, page.FollowersCount, page.LikesCount)

    ig, _ := socialapis.NewInstagram("YOUR_API_TOKEN")
    profile, err := ig.GetProfileDetails(ctx, "instagram", nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(profile.Username, profile.FollowersCount, profile.IsVerified)
}

Get a free API token → — 200 calls/month, no credit card

One-line migration

If you're moving from popular abandoned scraper packages, the migration aliases keep the import path greppable:

import socialapis "github.com/SocialAPIsHub/socialapis-go"

fb, _ := socialapis.NewFacebookScraper("YOUR_API_TOKEN")  // alias of Facebook
page, _ := fb.GetPageInfo(ctx, "EngenSA", nil)

FacebookScraper and InstagramScraper are Go type aliases (type FacebookScraper = Facebook) — identical type, identical method set, just different names. Defined in alias.go.

Idiomatic Go conventions

  • context.Context first: every endpoint method takes ctx context.Context as the first argument. Supports cancellation and timeouts via context.WithTimeout(...).
  • Functional options: client config via WithBaseURL(url), WithHTTPClient(client) instead of a settings struct. Easy to extend later without breaking existing callers.
  • Typed errors via errors.As: dispatch on *AuthenticationError, *RateLimitError, etc. — never string-match error messages.
  • Zero external dependencies: stdlib only (net/http, encoding/json, context). No deps in go.mod.
  • extra map[string]any: every method's last arg accepts arbitrary forward-compat query params. When the API adds a filter, you use it without an SDK release.

What's covered (v0.1.1)

Facebook client (35 methods)

Pages: GetPageID, GetPageInfo → *PageInfo, GetPagePosts, GetPageReels, GetPageVideos

Groups: GetGroupID, GetGroupDetails → *GroupInfo, GetGroupMetadata, GetGroupPosts, GetGroupVideos

Posts: GetPostID, GetPostDetails, GetPostDetailsExtended, GetPostComments, GetCommentReplies, GetPostAttachments, GetVideoPostDetails

Search: SearchPages, SearchPeople, SearchLocations, SearchPosts, SearchVideos

Meta Ads Library: GetAdsCountries, SearchAds, GetAdsPageDetails, GetAdArchiveDetails, SearchAdsByKeywords

Marketplace: SearchMarketplace, GetListingDetails, GetSellerDetails, GetMarketplaceCategories, GetCityCoordinates, SearchVehicles, SearchRentals

Media: DownloadMedia

Instagram client (13 methods)

Profiles: GetUserID, GetProfileDetails → *ProfileInfo, GetProfilePosts, GetProfileReels, GetProfileHighlights, GetHighlightDetails

Posts: GetPostID, GetPostDetails

Reels: GetReelsFeed, GetReelsByAudio

Search + Locations: Search, GetLocationPosts, GetNearbyLocations

Account client (3 methods)

Free — no credits charged.

GetUsage, GetTopUps, GetLimits

Pagination — no limit, cursor-based

The API decides page size. Take the cursor from the response and pass it back via extra:

fb, _ := socialapis.NewFacebook("YOUR_API_TOKEN")
ctx := context.Background()

result, _ := fb.GetPagePosts(ctx, "EngenSA", nil)
var allPosts []any
if posts, ok := result["posts"].([]any); ok {
    allPosts = append(allPosts, posts...)
}

for {
    cursor, _ := result["next_cursor"].(string)
    if cursor == "" {
        break
    }
    result, _ = fb.GetPagePosts(ctx, "EngenSA", map[string]any{"cursor": cursor})
    if posts, ok := result["posts"].([]any); ok {
        allPosts = append(allPosts, posts...)
    }
}

Forward-compat via extra

Every method accepts extra map[string]any for arbitrary query params:

fb.SearchAds(ctx, "fitness", map[string]any{
    "country":         "US",
    "activeStatus":    "Active",
    "some_new_filter": "x",
})
// → ?query=fitness&country=US&activeStatus=Active&some_new_filter=x

Error handling

Dispatch on typed errors with errors.As:

import (
    "errors"
    "log"
    "time"

    socialapis "github.com/SocialAPIsHub/socialapis-go"
)

page, err := fb.GetPageInfo(ctx, "EngenSA", nil)
if err != nil {
    var rateErr *socialapis.RateLimitError
    var creditsErr *socialapis.InsufficientCreditsError
    var authErr *socialapis.AuthenticationError

    switch {
    case errors.As(err, &rateErr):
        time.Sleep(time.Duration(rateErr.RetryAfterSeconds) * time.Second)
    case errors.As(err, &creditsErr):
        log.Fatal("Out of credits. Upgrade at https://socialapis.io/pricing")
    case errors.As(err, &authErr):
        log.Fatal("Bad token. Get one at https://socialapis.io/auth/signup")
    default:
        log.Fatal(err)
    }
}

Every typed error embeds APIError, which exposes .StatusCode, .RequestID, and .Body for debugging. The RequestID is what our backend logs — paste it into a support email and we can find the exact call.

Configuration

fb, err := socialapis.NewFacebook(
    "YOUR_API_TOKEN",
    socialapis.WithBaseURL("https://api.socialapis.io"),
    socialapis.WithHTTPClient(&http.Client{Timeout: 60 * time.Second}),
)
Custom HTTP client

Drop in your own http.Client for things like:

  • Custom timeouts beyond the default 30s
  • Retry middleware (e.g. wrap with github.com/hashicorp/go-retryablehttp)
  • Tracing via OpenTelemetry's otelhttp.NewTransport
  • Logging every request/response
client := &http.Client{
    Timeout:   60 * time.Second,
    Transport: otelhttp.NewTransport(http.DefaultTransport),
}
fb, _ := socialapis.NewFacebook("...", socialapis.WithHTTPClient(client))

Pricing

Tier Calls / month Price
Free 200 $0
Pro 1,500 $4.99
Ultra 30,000 $49
Mega 120,000 $179
Enterprise Custom Contact us

One credit per successful response. Failed calls (4xx caused by bad input) don't consume credits.

Other languages

Support

License

MIT — see LICENSE.

Documentation

Overview

Package socialapis is the Go SDK for the SocialAPIs.io REST API. It mirrors the Python `socialapis-sdk` and TypeScript `socialapis-sdk` — same endpoint coverage, idiomatic per-language conventions.

Index

Constants

View Source 
const DefaultBaseURL = "https://api.socialapis.io"

DefaultBaseURL is the production socialapis.io REST endpoint.

View Source 
const DefaultTimeout = 30 * time.Second

DefaultTimeout for HTTP requests when no per-call deadline is set via context.

View Source 
const Version = "0.1.1"

Version of the SDK. Bumped by the release workflow on `git tag vX.Y.Z`.

Lockstep with the Python (`socialapis-sdk` on PyPI) and JavaScript (`socialapis-sdk` on npm) SDKs in this family. All three start at 0.1.1 so users know the SDKs are at feature parity.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	Message    string
	StatusCode int
	RequestID  string
	Body       map[string]any
}

APIError is returned for any HTTP error response from the API. Specific 4xx/5xx flavours are typed below — use errors.As to dispatch.

func (*APIError) Error 

func (e *APIError) Error() string

type APIServerError 

type APIServerError struct{ APIError }

APIServerError is 5xx — the API failed. Safe to retry with backoff.

func (*APIServerError) Error 

func (e *APIServerError) Error() string

type Account 

type Account struct {
	// contains filtered or unexported fields
}

Account is the synchronous client for account-level endpoints — usage, credits, rate-limit info. None of these calls consume credits. 

acc, err := socialapis.NewAccount("YOUR_API_TOKEN")
usage, err := acc.GetUsage(ctx)

func NewAccount 

func NewAccount(apiToken string, opts ...Option) (*Account, error)

NewAccount constructs an Account client.

func (*Account) GetLimits 

func (a *Account) GetLimits(ctx context.Context) (Response, error)

GetLimits returns your plan's rate limit, concurrent-task cap, allowed packages.

func (*Account) GetTopUps 

func (a *Account) GetTopUps(ctx context.Context) (Response, error)

GetTopUps returns auto top-up settings + recent history + lifetime spend.

func (*Account) GetUsage 

func (a *Account) GetUsage(ctx context.Context) (Response, error)

GetUsage returns current credit balance, usage, plan, billing period. Free — does not consume credits.

type AuthenticationError 

type AuthenticationError struct{ APIError }

AuthenticationError is 401 — the API token is invalid or missing. Not retryable; the caller has to fix the token.

func (*AuthenticationError) Error 

func (e *AuthenticationError) Error() string

type BadRequestError 

type BadRequestError struct{ APIError }

BadRequestError is 4xx (excluding 401/402/429) — client-side mistake. NOT retryable without fixing input.

func (*BadRequestError) Error 

func (e *BadRequestError) Error() string

type ConnectionError 

type ConnectionError struct {
	Message string
	Cause   error
}

ConnectionError is a network failure / timeout / non-JSON response. Almost always transient. Safe to retry with backoff.

func (*ConnectionError) Error 

func (e *ConnectionError) Error() string

func (*ConnectionError) Unwrap 

func (e *ConnectionError) Unwrap() error

type Error 

type Error interface {
	error
	// contains filtered or unexported methods
}

Error is the base interface that every SDK-originating error satisfies. Callers can catch broadly with `errors.As(err, &socialapis.Error{...})` or narrowly with the typed subtypes below.

type Facebook 

type Facebook struct {
	// contains filtered or unexported fields
}

Facebook is the synchronous client for the Facebook surface of the SocialAPIs.io REST API. Construct with NewFacebook; every method takes a context.Context as the first argument (idiomatic Go). 

fb, err := socialapis.NewFacebook("YOUR_API_TOKEN")
if err != nil { ... }
ctx := context.Background()
page, err := fb.GetPageInfo(ctx, "EngenSA", nil)

FacebookScraper is an alias so users migrating from popular but abandoned scrapers can keep their import line greppable. See alias.go.

func NewFacebook 

func NewFacebook(apiToken string, opts ...Option) (*Facebook, error)

NewFacebook constructs a Facebook client. The apiToken is required.

Get a free key (200 calls/month, no card) at https://socialapis.io/auth/signup.

func (*Facebook) DownloadMedia 

func (f *Facebook) DownloadMedia(ctx context.Context, mediaURL string, extra map[string]any) (Response, error)

DownloadMedia resolves a Facebook video/photo URL to a downloadable URL.

func (*Facebook) GetAdArchiveDetails 

func (f *Facebook) GetAdArchiveDetails(ctx context.Context, adArchiveID, pageID string, extra map[string]any) (Response, error)

GetAdArchiveDetails returns detailed info for a specific archived ad.

func (*Facebook) GetAdsCountries 

func (f *Facebook) GetAdsCountries(ctx context.Context, extra map[string]any) (Response, error)

GetAdsCountries returns all country codes supported by the Meta Ads Library.

func (*Facebook) GetAdsPageDetails 

func (f *Facebook) GetAdsPageDetails(ctx context.Context, pageID string, extra map[string]any) (Response, error)

GetAdsPageDetails returns Ads-Library metadata for a Facebook Page.

func (*Facebook) GetCityCoordinates 

func (f *Facebook) GetCityCoordinates(ctx context.Context, city string, extra map[string]any) (Response, error)

GetCityCoordinates resolves a city name to GPS coordinates.

func (*Facebook) GetCommentReplies 

func (f *Facebook) GetCommentReplies(ctx context.Context, commentFeedbackID, expansionToken string, extra map[string]any) (Response, error)

GetCommentReplies returns replies to a specific comment. Both inputs come from GetPostComments when called with include_reply_info=true.

func (*Facebook) GetGroupDetails 

func (f *Facebook) GetGroupDetails(ctx context.Context, group string, extra map[string]any) (*GroupInfo, error)

GetGroupDetails returns typed GroupInfo. This endpoint has NO envelope wrapper — payload is at the top level.

func (*Facebook) GetGroupID 

func (f *Facebook) GetGroupID(ctx context.Context, group string, extra map[string]any) (Response, error)

GetGroupID returns the numeric Facebook Group ID.

func (*Facebook) GetGroupMetadata 

func (f *Facebook) GetGroupMetadata(ctx context.Context, group string, extra map[string]any) (Response, error)

GetGroupMetadata returns lightweight Group metadata (name, id, url, image).

func (*Facebook) GetGroupPosts 

func (f *Facebook) GetGroupPosts(ctx context.Context, group string, extra map[string]any) (Response, error)

GetGroupPosts returns recent posts from a Facebook Group.

func (*Facebook) GetGroupVideos 

func (f *Facebook) GetGroupVideos(ctx context.Context, groupID string, extra map[string]any) (Response, error)

GetGroupVideos returns videos posted to a Group (takes numeric group_id).

func (*Facebook) GetListingDetails 

func (f *Facebook) GetListingDetails(ctx context.Context, listingID string, extra map[string]any) (Response, error)

GetListingDetails returns full info for a Marketplace listing.

func (*Facebook) GetMarketplaceCategories 

func (f *Facebook) GetMarketplaceCategories(ctx context.Context, extra map[string]any) (Response, error)

GetMarketplaceCategories returns all Marketplace categories.

func (*Facebook) GetPageID 

func (f *Facebook) GetPageID(ctx context.Context, page string, extra map[string]any) (Response, error)

GetPageID returns the numeric Facebook Page ID for a URL or slug. Backed by GET /facebook/pages/id.

func (*Facebook) GetPageInfo 

func (f *Facebook) GetPageInfo(ctx context.Context, page string, extra map[string]any) (*PageInfo, error)

GetPageInfo returns typed metadata for a Facebook Page. Backed by GET /facebook/pages/details. Unwraps the API's "0"-keyed envelope before populating PageInfo.

func (*Facebook) GetPagePosts 

func (f *Facebook) GetPagePosts(ctx context.Context, page string, extra map[string]any) (Response, error)

GetPagePosts returns recent posts from a Facebook Page (cursor-paginated).

func (*Facebook) GetPageReels 

func (f *Facebook) GetPageReels(ctx context.Context, page string, extra map[string]any) (Response, error)

GetPageReels returns Reels (short videos) from a Facebook Page.

func (*Facebook) GetPageVideos 

func (f *Facebook) GetPageVideos(ctx context.Context, page string, extra map[string]any) (Response, error)

GetPageVideos returns long-form videos from a Facebook Page.

func (*Facebook) GetPostAttachments 

func (f *Facebook) GetPostAttachments(ctx context.Context, postID string, extra map[string]any) (Response, error)

GetPostAttachments returns all media attachments from a post.

func (*Facebook) GetPostComments 

func (f *Facebook) GetPostComments(ctx context.Context, post string, extra map[string]any) (Response, error)

GetPostComments returns comments on a Facebook post or reel. Pass include_reply_info="true" via extra to get reply cursors.

func (*Facebook) GetPostDetails 

func (f *Facebook) GetPostDetails(ctx context.Context, post string, extra map[string]any) (Response, error)

GetPostDetails returns full details of a Facebook post.

func (*Facebook) GetPostDetailsExtended 

func (f *Facebook) GetPostDetailsExtended(ctx context.Context, post string, extra map[string]any) (Response, error)

GetPostDetailsExtended returns extended post details (views, video URLs, music info).

func (*Facebook) GetPostID 

func (f *Facebook) GetPostID(ctx context.Context, post string, extra map[string]any) (Response, error)

GetPostID extracts the numeric Facebook post ID from a post URL.

func (*Facebook) GetSellerDetails 

func (f *Facebook) GetSellerDetails(ctx context.Context, sellerID string, extra map[string]any) (Response, error)

GetSellerDetails returns seller profile, ratings, reviews from Marketplace.

func (*Facebook) GetVideoPostDetails 

func (f *Facebook) GetVideoPostDetails(ctx context.Context, videoID string, extra map[string]any) (Response, error)

GetVideoPostDetails returns title, reactions, and play counts for a video post.

func (*Facebook) SearchAds 

func (f *Facebook) SearchAds(ctx context.Context, query string, extra map[string]any) (Response, error)

SearchAds searches ads in the Meta Ad Library by keyword.

func (*Facebook) SearchAdsByKeywords 

func (f *Facebook) SearchAdsByKeywords(ctx context.Context, query string, extra map[string]any) (Response, error)

SearchAdsByKeywords searches ads in the Ad Library by keyword + country.

func (*Facebook) SearchLocations 

func (f *Facebook) SearchLocations(ctx context.Context, query string, extra map[string]any) (Response, error)

SearchLocations searches Facebook for locations matching a keyword.

func (*Facebook) SearchMarketplace 

func (f *Facebook) SearchMarketplace(ctx context.Context, query string, extra map[string]any) (Response, error)

SearchMarketplace searches Facebook Marketplace listings.

func (*Facebook) SearchPages 

func (f *Facebook) SearchPages(ctx context.Context, query string, extra map[string]any) (Response, error)

SearchPages searches Facebook pages by keyword. Pass location_id via extra for geo filtering.

func (*Facebook) SearchPeople 

func (f *Facebook) SearchPeople(ctx context.Context, query string, extra map[string]any) (Response, error)

SearchPeople searches Facebook profiles by keyword.

func (*Facebook) SearchPosts 

func (f *Facebook) SearchPosts(ctx context.Context, query string, extra map[string]any) (Response, error)

SearchPosts searches Facebook posts by keyword.

func (*Facebook) SearchRentals 

func (f *Facebook) SearchRentals(ctx context.Context, extra map[string]any) (Response, error)

SearchRentals searches Marketplace rental-property listings.

func (*Facebook) SearchVehicles 

func (f *Facebook) SearchVehicles(ctx context.Context, extra map[string]any) (Response, error)

SearchVehicles searches Marketplace vehicle listings. Requires lat/lng filters via extra.

func (*Facebook) SearchVideos 

func (f *Facebook) SearchVideos(ctx context.Context, query string, extra map[string]any) (Response, error)

SearchVideos searches Facebook videos by keyword.

type FacebookScraper 

type FacebookScraper = Facebook

FacebookScraper is an alias for Facebook. It exists so users migrating from popular abandoned scrapers can keep their import path / type name greppable in their codebase.

FacebookScraper and Facebook are the EXACT same type — not a wrapper.

func NewFacebookScraper 

func NewFacebookScraper(apiToken string, opts ...Option) (*FacebookScraper, error)

NewFacebookScraper constructs a FacebookScraper (= Facebook) client.

Provided as a sibling to NewFacebook so the migration story stays a one-line constructor swap.

type GroupInfo 

type GroupInfo struct {
	GroupID                   string         `json:"group_id,omitempty"`
	GroupMemberCount          string         `json:"group_member_count,omitempty"`
	GroupTotalMembersInfoText string         `json:"group_total_members_info_text,omitempty"`
	GroupNewMembersInfoText   string         `json:"group_new_members_info_text,omitempty"`
	DescriptionText           string         `json:"description_text,omitempty"`
	PrivacyInfoText           map[string]any `json:"privacy_info_text,omitempty"`
	CreatedTime               int64          `json:"created_time,omitempty"`
	GroupRules                []any          `json:"group_rules,omitempty"`
	GroupHistory              map[string]any `json:"group_history,omitempty"`
	AdminTags                 []any          `json:"admin_tags,omitempty"`
	GroupLocations            []any          `json:"group_locations,omitempty"`
	NumberOfPostsInLastDay    int            `json:"number_of_posts_in_last_day,omitempty"`
	NumberOfPostsInLastMonth  int            `json:"number_of_posts_in_last_month,omitempty"`

	// Forward-compat
	Extra map[string]any `json:"-"`
}

GroupInfo is the response from `Facebook.GetGroupDetails()` — `GET /facebook/groups/details`.

NOTE: this endpoint has NO envelope wrapper — payload sits at the top level alongside `message` and `meta`.

type HTTPDoer 

type HTTPDoer interface {
	Do(*http.Request) (*http.Response, error)
}

HTTPDoer is the minimum interface the SDK needs from an HTTP client. stdlib's *http.Client satisfies this. Custom implementations (e.g. adding retry logic, metrics, or per-request tracing) can also be dropped in via WithHTTPClient.

type Instagram 

type Instagram struct {
	// contains filtered or unexported fields
}

Instagram is the synchronous client for the Instagram surface of the SocialAPIs.io REST API. Same shape as Facebook — every method takes ctx context.Context as the first argument. 

ig, err := socialapis.NewInstagram("YOUR_API_TOKEN")
profile, err := ig.GetProfileDetails(ctx, "instagram", nil)

func NewInstagram 

func NewInstagram(apiToken string, opts ...Option) (*Instagram, error)

NewInstagram constructs an Instagram client.

func (*Instagram) GetHighlightDetails 

func (i *Instagram) GetHighlightDetails(ctx context.Context, highlightID string, extra map[string]any) (Response, error)

GetHighlightDetails returns all stories within a specific Highlight.

func (*Instagram) GetLocationPosts 

func (i *Instagram) GetLocationPosts(ctx context.Context, locationID string, extra map[string]any) (Response, error)

GetLocationPosts returns posts tagged at a specific Instagram location. Pass tab="ranked" or tab="recent" via extra.

func (*Instagram) GetNearbyLocations 

func (i *Instagram) GetNearbyLocations(ctx context.Context, locationID string, extra map[string]any) (Response, error)

GetNearbyLocations returns Instagram locations near a given location.

func (*Instagram) GetPostDetails 

func (i *Instagram) GetPostDetails(ctx context.Context, shortcode string, extra map[string]any) (Response, error)

GetPostDetails returns full Instagram post details.

func (*Instagram) GetPostID 

func (i *Instagram) GetPostID(ctx context.Context, post string, extra map[string]any) (Response, error)

GetPostID extracts the shortcode/ID from any Instagram post URL.

func (*Instagram) GetProfileDetails 

func (i *Instagram) GetProfileDetails(ctx context.Context, username string, extra map[string]any) (*ProfileInfo, error)

GetProfileDetails returns typed ProfileInfo for an Instagram username. Unwraps the API's "data"-keyed envelope before populating.

func (*Instagram) GetProfileHighlights 

func (i *Instagram) GetProfileHighlights(ctx context.Context, userID string, extra map[string]any) (Response, error)

GetProfileHighlights returns all Story Highlights for a profile.

func (*Instagram) GetProfilePosts 

func (i *Instagram) GetProfilePosts(ctx context.Context, username string, extra map[string]any) (Response, error)

GetProfilePosts returns recent posts from an Instagram profile.

func (*Instagram) GetProfileReels 

func (i *Instagram) GetProfileReels(ctx context.Context, userID string, extra map[string]any) (Response, error)

GetProfileReels returns Reels for an Instagram profile. Takes a numeric user_id (use GetUserID to resolve a username first).

func (*Instagram) GetReelsByAudio 

func (i *Instagram) GetReelsByAudio(ctx context.Context, audioID string, extra map[string]any) (Response, error)

GetReelsByAudio returns all Reels using a specific audio track.

func (*Instagram) GetReelsFeed 

func (i *Instagram) GetReelsFeed(ctx context.Context, extra map[string]any) (Response, error)

GetReelsFeed returns the trending Reels feed.

func (*Instagram) GetUserID 

func (i *Instagram) GetUserID(ctx context.Context, profile string, extra map[string]any) (Response, error)

GetUserID returns the numeric Instagram user ID for a username or URL.

func (*Instagram) Search 

func (i *Instagram) Search(ctx context.Context, keyword string, extra map[string]any) (Response, error)

Search returns popular Instagram results — users, hashtags, places.

type InstagramScraper 

type InstagramScraper = Instagram

InstagramScraper is an alias for Instagram. Same migration story as FacebookScraper.

func NewInstagramScraper 

func NewInstagramScraper(apiToken string, opts ...Option) (*InstagramScraper, error)

NewInstagramScraper constructs an InstagramScraper (= Instagram) client.

type InsufficientCreditsError 

type InsufficientCreditsError struct{ APIError }

InsufficientCreditsError is 402 — credit balance exhausted. Retryable after refill / upgrade. Tracked as a distinct error so paid integrations can auto-top-up on this signal.

func (*InsufficientCreditsError) Error 

func (e *InsufficientCreditsError) Error() string

type Option 

type Option func(*baseConfig)

Option configures a Facebook / Instagram / Account client. Use the `With...` functions below — they cover every configurable behaviour.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the API base URL. Useful for staging or local mock servers.

func WithHTTPClient 

func WithHTTPClient(client HTTPDoer) Option

WithHTTPClient lets callers pass a custom HTTPDoer (typically an *http.Client with a different timeout or transport).

type PageInfo 

type PageInfo struct {
	// Identifiers
	AdPageID string `json:"ad_page_id,omitempty"`
	UserID   string `json:"user_id,omitempty"`

	// Display
	Title    string `json:"title,omitempty"`
	URL      string `json:"url,omitempty"`
	Category any    `json:"category,omitempty"` // can be a list or a string
	Status   string `json:"status,omitempty"`

	// Content
	Bio         string `json:"bio,omitempty"`
	Description string `json:"description,omitempty"`

	// Contact
	Address     string `json:"address,omitempty"`
	Phone       string `json:"phone,omitempty"`
	Email       string `json:"email,omitempty"`
	Website     string `json:"website,omitempty"`
	MapsAddress string `json:"maps_address,omitempty"`

	// Engagement
	FollowersCount   int    `json:"followers_count,omitempty"`
	FollowersDisplay string `json:"followers_display,omitempty"`
	LikesCount       int    `json:"likes_count,omitempty"`
	LikesDisplay     string `json:"likes_display,omitempty"`

	// Media
	Image    string `json:"image,omitempty"`
	ImageAlt string `json:"image_alt,omitempty"`

	// Ratings
	Rating        string `json:"rating,omitempty"`
	RatingCount   int    `json:"rating_count,omitempty"`
	RatingOverall string `json:"rating_overall,omitempty"`

	// Business
	BusinessHours        string `json:"business_hours,omitempty"`
	BusinessPrice        string `json:"business_price,omitempty"`
	BusinessServices     string `json:"business_services,omitempty"`
	IsBusinessPageActive bool   `json:"is_business_page_active,omitempty"`
	ConfirmedOwnerLabel  string `json:"confirmed_owner_label,omitempty"`

	// Linked socials
	Twitter   string `json:"twitter,omitempty"`
	Instagram string `json:"instagram,omitempty"`
	LinkedIn  string `json:"linkedin,omitempty"`
	Pinterest string `json:"pinterest,omitempty"`
	Telegram  string `json:"telegram,omitempty"`
	YouTube   string `json:"youtube,omitempty"`

	// Forward-compat — any field the API adds that we haven't typed yet
	Extra map[string]any `json:"-"`
}

PageInfo is the response from `Facebook.GetPageInfo()` — `GET /facebook/pages/details`.

The API wraps this payload under string key "0" in the response envelope; the SDK unwraps before returning. Field names match the LIVE API exactly (verified 2026-06-22).

Forward-compat: any field the API adds that we haven't typed yet lives on Extra — access via `page.Extra["new_field"]`.

type ProfileInfo 

type ProfileInfo struct {
	// Identifiers
	ID   string `json:"id,omitempty"`
	PK   string `json:"pk,omitempty"`
	FBID string `json:"fbid,omitempty"`

	// Display
	Username     string `json:"username,omitempty"`
	FullName     string `json:"full_name,omitempty"`
	Biography    string `json:"biography,omitempty"`
	CategoryName string `json:"category_name,omitempty"`

	// Media URLs
	ProfilePicURL          string `json:"profile_pic_url,omitempty"`
	ProfilePicURLHD        string `json:"profile_pic_url_hd,omitempty"`
	ExternalURL            string `json:"external_url,omitempty"`
	ExternalURLLinkshimmed string `json:"external_url_linkshimmed,omitempty"`

	// Counts
	FollowersCount       int `json:"followers_count,omitempty"`
	FollowingCount       int `json:"following_count,omitempty"`
	MediaCount           int `json:"media_count,omitempty"`
	TotalClipsCount      int `json:"total_clips_count,omitempty"`
	HighlightReelCount   int `json:"highlight_reel_count,omitempty"`
	MutualFollowersCount int `json:"mutual_followers_count,omitempty"`

	// Flags
	IsPrivate             bool `json:"is_private,omitempty"`
	IsVerified            bool `json:"is_verified,omitempty"`
	IsBusinessAccount     bool `json:"is_business_account,omitempty"`
	IsProfessionalAccount bool `json:"is_professional_account,omitempty"`
	IsMemorialized        bool `json:"is_memorialized,omitempty"`
	IsUnpublished         bool `json:"is_unpublished,omitempty"`
	IsEmbedsDisabled      bool `json:"is_embeds_disabled,omitempty"`
	IsJoinedRecently      bool `json:"is_joined_recently,omitempty"`
	AccountType           int  `json:"account_type,omitempty"`

	// Features
	HasClips     bool `json:"has_clips,omitempty"`
	HasGuides    bool `json:"has_guides,omitempty"`
	HasChannel   bool `json:"has_channel,omitempty"`
	HasArEffects bool `json:"has_ar_effects,omitempty"`

	// Business contact
	BusinessCategoryName  string `json:"business_category_name,omitempty"`
	BusinessEmail         string `json:"business_email,omitempty"`
	BusinessPhoneNumber   string `json:"business_phone_number,omitempty"`
	BusinessContactMethod string `json:"business_contact_method,omitempty"`
	AddressStreet         string `json:"address_street,omitempty"`
	CityName              string `json:"city_name,omitempty"`
	Zip                   string `json:"zip,omitempty"`

	// Forward-compat
	Extra map[string]any `json:"-"`
}

ProfileInfo is the response from `Instagram.GetProfileDetails()` — `GET /instagram/profile/details`.

The API wraps the payload under "data" in the envelope (alongside `success`, `message`, `meta`); the SDK unwraps before returning.

type RateLimitError 

type RateLimitError struct {
	APIError
	RetryAfterSeconds float64
}

RateLimitError is 429 — too many requests. Retryable after the RetryAfterSeconds interval (parsed from the Retry-After header).

func (*RateLimitError) Error 

func (e *RateLimitError) Error() string

type Response 

type Response map[string]any

Response is the generic untyped response a method returns when the endpoint doesn't have a hand-typed struct yet. Most endpoints in v0.1.0 return Response — only the three headline endpoints return typed structs (PageInfo, GroupInfo, ProfileInfo).

Forward-compat: any field the API returns is preserved in the map regardless of whether we've typed it; callers can access via `r["some_field"]`.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.