supadata

package module
v0.1.4 Latest Latest
Warning

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

 Go to latest Published: Jan 6, 2026 License: MIT Imports: 7 Imported by: 0

README

supadata-go

Go Reference Go Report Card CI

Go SDK for the Supadata API - extract transcripts from YouTube, Instagram, and other video platforms.

This is an UNOFFICIAL library and is not affiliated with https://supadata.ai/

Supported Features

OpenAPI specification: https://supadata.ai/api/v1/openapi.json

Endpoint Supported
Universal Transcript ✅
Universal Transcript Result ✅
Universal Metadata ✅
Youtube Search ✅
Youtube Video ✅
Youtube Video Batch ✅
Youtube Transcript ✅
Youtube Transcript Batch ✅
Youtube Transcript Translate ✅
Youtube Channel ✅
Youtube Playlist ✅
Youtube Channel Videos ✅
Youtube Playlist Videos ✅
Youtube Batch Result ✅
Web Scrape ✅
Web Map ✅
Web Crawl ✅
Web Crawl Status ✅
Account Information ✅

Installation

go get github.com/petros0/supadata-go

Quick Start

package main

import (
	"fmt"

	supadata "github.com/petros0/supadata-go"
)

func main() {
	client := supadata.NewSupadata() // Will use SUPADATA_API_KEY env var

	transcript, err := client.Transcript(&supadata.TranscriptParams{
		Url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
	})
	if err != nil {
		panic(err)
	}

	if transcript.IsAsync() {
		fmt.Println("Job ID:", transcript.Async.JobId)
	} else {
		for _, segment := range transcript.Sync.Content {
			fmt.Println(segment.Text)
		}
	}
}

Development

The project uses https://asdf-vm.com/guide/getting-started.html for version management. To set up the development environment, run:

asdf install

Examples

See the example folder for more usage examples.

To run the examples, set your API key as an environment variable and execute the main file:

export SUPADATA_API_KEY=your_api_key
go run ./example

Configuration

API Key

You can provide your API key in two ways:

  1. Environment variable (recommended):
export SUPADATA_API_KEY=your_api_key

client := supadata.NewSupadata() // Will use SUPADATA_API_KEY env var
  1. Explicit configuration:
client := supadata.NewSupadata(
    WithAPIKey("sd_..."),
    WithTimeout(30*time.Second), // just override timeout of the client
)
Custom HTTP client

You can provide a custom HTTP client for advanced use cases:

client := supadata.NewSupadata(
	WithAPIKey("sd_..."),
	WithClient(
		&http.Client{
            Timeout:   30 * time.Second,
            Transport: http.DefaultTransport,
        },
    ),
)

License

MIT License - see LICENSE for details.

Documentation

Index

Constants

View Source 
const (
	BaseUrl = "https://api.supadata.ai/v1"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AccountInfo added in v0.1.4 

type AccountInfo struct {
	OrganizationId string `json:"organizationId"`
	Plan           string `json:"plan"`
	MaxCredits     int    `json:"maxCredits"`
	UsedCredits    int    `json:"usedCredits"`
}

type AsyncTranscript 

type AsyncTranscript struct {
	JobId string `json:"jobId"`
}

type Config added in v0.1.3 

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

type ConfigOption added in v0.1.3 

type ConfigOption func(*Config)

func WithAPIKey 

func WithAPIKey(apiKey string) ConfigOption

func WithBaseURL added in v0.1.3 

func WithBaseURL(baseURL string) ConfigOption

func WithClient 

func WithClient(client *http.Client) ConfigOption

func WithTimeout 

func WithTimeout(timeout time.Duration) ConfigOption

type CrawlBody added in v0.1.4 

type CrawlBody struct {
	Url   string `json:"url"`
	Limit int    `json:"limit,omitempty"`
}

type CrawlJob added in v0.1.4 

type CrawlJob struct {
	JobId string `json:"jobId"`
}

type CrawlPage added in v0.1.4 

type CrawlPage struct {
	Url             string `json:"url"`
	Content         string `json:"content"`
	Name            string `json:"name"`
	Description     string `json:"description"`
	OgUrl           string `json:"ogUrl"`
	CountCharacters int    `json:"countCharacters"`
}

type CrawlResult added in v0.1.4 

type CrawlResult struct {
	Status CrawlStatus `json:"status"`
	Pages  []CrawlPage `json:"pages,omitempty"`
	Next   string      `json:"next,omitempty"`
}

type CrawlStatus added in v0.1.4 

type CrawlStatus string

CrawlStatus represents the status of a crawl job 

const (
	Scraping       CrawlStatus = "scraping"
	CrawlCompleted CrawlStatus = "completed"
	CrawlFailed    CrawlStatus = "failed"
	Cancelled      CrawlStatus = "cancelled"
)

type ErrorIdentifier 

type ErrorIdentifier string
const (
	InvalidRequest        ErrorIdentifier = "invalid-request"
	InternalError         ErrorIdentifier = "internal-error"
	Forbidden             ErrorIdentifier = "forbidden"
	Unauthorized          ErrorIdentifier = "unauthorized"
	UpgradeRequired       ErrorIdentifier = "upgrade-required"
	TranscriptUnavailable ErrorIdentifier = "transcript-unavailable"
	NotFound              ErrorIdentifier = "not-found"
	LimitExceeded         ErrorIdentifier = "limit-exceeded"
)

type ErrorResponse 

type ErrorResponse struct {
	ErrorIdentifier  ErrorIdentifier `json:"error"`
	Message          string          `json:"message"`
	Details          string          `json:"details"`
	DocumentationUrl string          `json:"documentationUrl"`
}

func (*ErrorResponse) Error 

func (e *ErrorResponse) Error() string

type MapParams added in v0.1.4 

type MapParams struct {
	Url     string
	NoLinks bool
	Lang    string
}

type MapResult added in v0.1.4 

type MapResult struct {
	Urls []string `json:"urls"`
}

type Metadata 

type Metadata struct {
	Platform    MetadataPlatform `json:"platform"`
	Type        MetadataType     `json:"type"`
	Id          string           `json:"id"`
	Url         string           `json:"url"`
	Title       string           `json:"title"`
	Description string           `json:"description"`
	Author      struct {
		DisplayName string `json:"displayName"`
		Username    string `json:"username"`
		AvatarUrl   string `json:"avatarUrl"`
		Verified    bool   `json:"verified"`
	} `json:"author"`
	Stats struct {
		Likes    *int `json:"likes"`
		Comments *int `json:"comments"`
		Shares   *int `json:"shares"`
		Views    *int `json:"views"`
	} `json:"stats"`
	Media struct {
		Type         string  `json:"type"`
		Duration     float64 `json:"duration,omitempty"`
		ThumbnailUrl string  `json:"thumbnailUrl,omitempty"`
		Url          string  `json:"url,omitempty"`
		Items        []struct {
			Type         string  `json:"type"`
			Duration     float64 `json:"duration,omitempty"`
			ThumbnailUrl string  `json:"thumbnailUrl,omitempty"`
			Url          string  `json:"url,omitempty"`
		} `json:"items,omitempty"`
	} `json:"media"`
	Tags           []string       `json:"tags,omitempty"`
	CreatedAt      time.Time      `json:"createdAt"`
	AdditionalData map[string]any `json:"additionalData,omitempty"`
}

type MetadataPlatform 

type MetadataPlatform string
const (
	YouTube   MetadataPlatform = "youtube"
	TikTok    MetadataPlatform = "tiktok"
	Instagram MetadataPlatform = "instagram"
	Twitter   MetadataPlatform = "twitter"
	Facebook  MetadataPlatform = "facebook"
)

type MetadataType 

type MetadataType string
const (
	Video    MetadataType = "video"
	Image    MetadataType = "image"
	Carousel MetadataType = "carousel"
	Post     MetadataType = "post"
)

type ScrapeParams added in v0.1.4 

type ScrapeParams struct {
	Url     string
	NoLinks bool
	Lang    string
}

type ScrapeResult added in v0.1.4 

type ScrapeResult struct {
	Url             string   `json:"url"`
	Content         string   `json:"content"`
	Name            string   `json:"name"`
	Description     string   `json:"description"`
	OgUrl           string   `json:"ogUrl"`
	CountCharacters int      `json:"countCharacters"`
	Urls            []string `json:"urls"`
}

type Supadata 

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

func NewSupadata 

func NewSupadata(opts ...ConfigOption) *Supadata

func (*Supadata) Crawl added in v0.1.4 

func (s *Supadata) Crawl(params *CrawlBody) (*CrawlJob, error)

Crawl initiates an async crawl job for a website

func (*Supadata) CrawlResult added in v0.1.4 

func (s *Supadata) CrawlResult(jobId string, skip int) (*CrawlResult, error)

CrawlResult retrieves the status and results of a crawl job

func (*Supadata) Map added in v0.1.4 

func (s *Supadata) Map(params *MapParams) (*MapResult, error)

Map discovers all URLs on a website

func (*Supadata) Me added in v0.1.4 

func (s *Supadata) Me() (*AccountInfo, error)

Me retrieves account information

func (*Supadata) Metadata 

func (s *Supadata) Metadata(url string) (*Metadata, error)

Metadata retrieves metadata for a given URL

func (*Supadata) Scrape added in v0.1.4 

func (s *Supadata) Scrape(params *ScrapeParams) (*ScrapeResult, error)

Scrape extracts content from a webpage as markdown

func (*Supadata) Transcript 

func (s *Supadata) Transcript(params *TranscriptParams) (*Transcript, error)

Transcript initiates a transcript request (sync or async)

func (*Supadata) TranscriptResult 

func (s *Supadata) TranscriptResult(jobId string) (*TranscriptResult, error)

TranscriptResult retrieves the result of an async transcript job

func (*Supadata) YouTubeBatchResult added in v0.1.4 

func (s *Supadata) YouTubeBatchResult(jobId string) (*YouTubeBatchResult, error)

YouTubeBatchResult retrieves the status and results of a batch job

func (*Supadata) YouTubeChannel added in v0.1.4 

func (s *Supadata) YouTubeChannel(id string) (*YouTubeChannel, error)

YouTubeChannel retrieves metadata for a YouTube channel

func (*Supadata) YouTubeChannelVideos added in v0.1.4 

func (s *Supadata) YouTubeChannelVideos(params *YouTubeChannelVideosParams) (*YouTubeChannelVideosResult, error)

YouTubeChannelVideos retrieves video IDs from a YouTube channel

func (*Supadata) YouTubePlaylist added in v0.1.4 

func (s *Supadata) YouTubePlaylist(id string) (*YouTubePlaylist, error)

YouTubePlaylist retrieves metadata for a YouTube playlist

func (*Supadata) YouTubePlaylistVideos added in v0.1.4 

func (s *Supadata) YouTubePlaylistVideos(params *YouTubePlaylistVideosParams) (*YouTubePlaylistVideosResult, error)

YouTubePlaylistVideos retrieves video IDs from a YouTube playlist

func (*Supadata) YouTubeSearch added in v0.1.4 

func (s *Supadata) YouTubeSearch(params *YouTubeSearchParams) (*YouTubeSearchResult, error)

YouTubeSearch searches YouTube for videos, channels, or playlists

func (*Supadata) YouTubeTranscript added in v0.1.4 

func (s *Supadata) YouTubeTranscript(params *YouTubeTranscriptParams) (*YouTubeTranscriptResult, error)

YouTubeTranscript retrieves the transcript for a YouTube video

func (*Supadata) YouTubeTranscriptBatch added in v0.1.4 

func (s *Supadata) YouTubeTranscriptBatch(params *YouTubeTranscriptBatchParams) (*YouTubeBatchJob, error)

YouTubeTranscriptBatch initiates a batch job to retrieve transcripts for multiple videos

func (*Supadata) YouTubeTranscriptTranslate added in v0.1.4 

func (s *Supadata) YouTubeTranscriptTranslate(params *YouTubeTranscriptTranslateParams) (*YouTubeTranscriptTranslateResult, error)

YouTubeTranscriptTranslate retrieves a translated transcript for a YouTube video

func (*Supadata) YouTubeVideo added in v0.1.4 

func (s *Supadata) YouTubeVideo(id string) (*YouTubeVideo, error)

YouTubeVideo retrieves metadata for a YouTube video

func (*Supadata) YouTubeVideoBatch added in v0.1.4 

func (s *Supadata) YouTubeVideoBatch(params *YouTubeVideoBatchParams) (*YouTubeBatchJob, error)

YouTubeVideoBatch initiates a batch job to retrieve multiple video metadata

type SyncTranscript 

type SyncTranscript struct {
	Content        []TranscriptContent `json:"content"`
	Lang           string              `json:"lang"`
	AvailableLangs []string            `json:"availableLangs"`
}

type Transcript 

type Transcript struct {
	Sync  *SyncTranscript
	Async *AsyncTranscript
}

func (*Transcript) IsAsync 

func (r *Transcript) IsAsync() bool

type TranscriptContent 

type TranscriptContent struct {
	Text     string  `json:"text"`
	Offset   float64 `json:"offset"`
	Duration float64 `json:"duration"`
	Lang     string  `json:"lang"`
}

type TranscriptModeParam 

type TranscriptModeParam string
const (
	Native   TranscriptModeParam = "native"
	Auto     TranscriptModeParam = "auto"
	Generate TranscriptModeParam = "generate"
)

type TranscriptParams 

type TranscriptParams struct {
	Url       string
	Lang      string
	Text      bool
	ChunkSize int
	Mode      TranscriptModeParam
}

type TranscriptResult 

type TranscriptResult struct {
	Status         TranscriptResultStatus `json:"status"`
	Error          *ErrorResponse         `json:"error,omitempty"`
	Content        []TranscriptContent    `json:"content,omitempty"`
	Lang           string                 `json:"lang,omitempty"`
	AvailableLangs []string               `json:"availableLangs,omitempty"`
}

type TranscriptResultStatus 

type TranscriptResultStatus string
const (
	Queued    TranscriptResultStatus = "queued"
	Active    TranscriptResultStatus = "active"
	Completed TranscriptResultStatus = "completed"
	Failed    TranscriptResultStatus = "failed"
)

type YouTubeBatchJob added in v0.1.4 

type YouTubeBatchJob struct {
	JobId string `json:"jobId"`
}

type YouTubeBatchResult added in v0.1.4 

type YouTubeBatchResult struct {
	Status      YouTubeBatchStatus       `json:"status"`
	Results     []YouTubeBatchResultItem `json:"results,omitempty"`
	Stats       YouTubeBatchStats        `json:"stats"`
	CompletedAt *string                  `json:"completedAt,omitempty"`
}

type YouTubeBatchResultItem added in v0.1.4 

type YouTubeBatchResultItem struct {
	VideoId    string                   `json:"videoId"`
	Transcript *YouTubeTranscriptResult `json:"transcript,omitempty"`
	Video      *YouTubeVideo            `json:"video,omitempty"`
	ErrorCode  string                   `json:"errorCode,omitempty"`
}

type YouTubeBatchStats added in v0.1.4 

type YouTubeBatchStats struct {
	Total     int `json:"total"`
	Succeeded int `json:"succeeded"`
	Failed    int `json:"failed"`
}

type YouTubeBatchStatus added in v0.1.4 

type YouTubeBatchStatus string

YouTubeBatchStatus represents the status of a batch job 

const (
	BatchQueued    YouTubeBatchStatus = "queued"
	BatchActive    YouTubeBatchStatus = "active"
	BatchCompleted YouTubeBatchStatus = "completed"
	BatchFailed    YouTubeBatchStatus = "failed"
)

type YouTubeChannel added in v0.1.4 

type YouTubeChannel struct {
	Id              string `json:"id"`
	Name            string `json:"name"`
	Description     string `json:"description,omitempty"`
	SubscriberCount *int   `json:"subscriberCount,omitempty"`
	VideoCount      *int   `json:"videoCount,omitempty"`
	ViewCount       *int   `json:"viewCount,omitempty"`
	Thumbnail       string `json:"thumbnail,omitempty"`
	Banner          string `json:"banner,omitempty"`
}

type YouTubeChannelVideoType added in v0.1.4 

type YouTubeChannelVideoType string

YouTubeChannelVideoType filter for channel videos 

const (
	ChannelVideoTypeAll   YouTubeChannelVideoType = "all"
	ChannelVideoTypeVideo YouTubeChannelVideoType = "video"
	ChannelVideoTypeShort YouTubeChannelVideoType = "short"
	ChannelVideoTypeLive  YouTubeChannelVideoType = "live"
)

type YouTubeChannelVideosParams added in v0.1.4 

type YouTubeChannelVideosParams struct {
	Id    string
	Limit int
	Type  YouTubeChannelVideoType
}

type YouTubeChannelVideosResult added in v0.1.4 

type YouTubeChannelVideosResult struct {
	VideoIds []string `json:"videoIds"`
	ShortIds []string `json:"shortIds"`
	LiveIds  []string `json:"liveIds"`
}

type YouTubePlaylist added in v0.1.4 

type YouTubePlaylist struct {
	Id          string              `json:"id"`
	Title       string              `json:"title"`
	Description string              `json:"description,omitempty"`
	VideoCount  int                 `json:"videoCount"`
	ViewCount   *int                `json:"viewCount,omitempty"`
	LastUpdated *string             `json:"lastUpdated,omitempty"`
	Channel     YouTubeVideoChannel `json:"channel"`
}

type YouTubePlaylistVideosParams added in v0.1.4 

type YouTubePlaylistVideosParams struct {
	Id    string
	Limit int
}

type YouTubePlaylistVideosResult added in v0.1.4 

type YouTubePlaylistVideosResult struct {
	VideoIds []string `json:"videoIds"`
	ShortIds []string `json:"shortIds"`
	LiveIds  []string `json:"liveIds"`
}

type YouTubeSearchDuration added in v0.1.4 

type YouTubeSearchDuration string

YouTubeSearchDuration filter for search results 

const (
	DurationAll    YouTubeSearchDuration = "all"
	DurationShort  YouTubeSearchDuration = "short"
	DurationMedium YouTubeSearchDuration = "medium"
	DurationLong   YouTubeSearchDuration = "long"
)

type YouTubeSearchFeature added in v0.1.4 

type YouTubeSearchFeature string

YouTubeSearchFeature special features filter 

const (
	FeatureHD             YouTubeSearchFeature = "hd"
	FeatureSubtitles      YouTubeSearchFeature = "subtitles"
	FeatureCreativeCommon YouTubeSearchFeature = "creative-commons"
	Feature3D             YouTubeSearchFeature = "3d"
	FeatureLive           YouTubeSearchFeature = "live"
	Feature4K             YouTubeSearchFeature = "4k"
	Feature360            YouTubeSearchFeature = "360"
	FeatureLocation       YouTubeSearchFeature = "location"
	FeatureHDR            YouTubeSearchFeature = "hdr"
	FeatureVR180          YouTubeSearchFeature = "vr180"
)

type YouTubeSearchParams added in v0.1.4 

type YouTubeSearchParams struct {
	Query         string
	UploadDate    YouTubeSearchUploadDate
	Type          YouTubeSearchType
	Duration      YouTubeSearchDuration
	SortBy        YouTubeSearchSortBy
	Features      []YouTubeSearchFeature
	Limit         int
	NextPageToken string
}

type YouTubeSearchResult added in v0.1.4 

type YouTubeSearchResult struct {
	Query         string                    `json:"query"`
	Results       []YouTubeSearchResultItem `json:"results"`
	TotalResults  int                       `json:"totalResults"`
	NextPageToken string                    `json:"nextPageToken,omitempty"`
}

type YouTubeSearchResultItem added in v0.1.4 

type YouTubeSearchResultItem struct {
	Type            string `json:"type"`
	Id              string `json:"id"`
	Title           string `json:"title"`
	Description     string `json:"description"`
	Thumbnail       string `json:"thumbnail"`
	Duration        int    `json:"duration,omitempty"`
	ViewCount       *int   `json:"viewCount,omitempty"`
	UploadDate      string `json:"uploadDate,omitempty"`
	ChannelId       string `json:"channelId,omitempty"`
	ChannelName     string `json:"channelName,omitempty"`
	SubscriberCount *int   `json:"subscriberCount,omitempty"`
	VideoCount      *int   `json:"videoCount,omitempty"`
}

type YouTubeSearchSortBy added in v0.1.4 

type YouTubeSearchSortBy string

YouTubeSearchSortBy sort order for search results 

const (
	SortByRelevance YouTubeSearchSortBy = "relevance"
	SortByRating    YouTubeSearchSortBy = "rating"
	SortByDate      YouTubeSearchSortBy = "date"
	SortByViews     YouTubeSearchSortBy = "views"
)

type YouTubeSearchType added in v0.1.4 

type YouTubeSearchType string

YouTubeSearchType filter for search results 

const (
	SearchTypeAll      YouTubeSearchType = "all"
	SearchTypeVideo    YouTubeSearchType = "video"
	SearchTypeChannel  YouTubeSearchType = "channel"
	SearchTypePlaylist YouTubeSearchType = "playlist"
	SearchTypeMovie    YouTubeSearchType = "movie"
)

type YouTubeSearchUploadDate added in v0.1.4 

type YouTubeSearchUploadDate string

YouTubeSearchUploadDate filter for search results 

const (
	UploadDateAll   YouTubeSearchUploadDate = "all"
	UploadDateHour  YouTubeSearchUploadDate = "hour"
	UploadDateToday YouTubeSearchUploadDate = "today"
	UploadDateWeek  YouTubeSearchUploadDate = "week"
	UploadDateMonth YouTubeSearchUploadDate = "month"
	UploadDateYear  YouTubeSearchUploadDate = "year"
)

type YouTubeTranscriptBatchParams added in v0.1.4 

type YouTubeTranscriptBatchParams struct {
	VideoIds   []string `json:"videoIds,omitempty"`
	PlaylistId string   `json:"playlistId,omitempty"`
	ChannelId  string   `json:"channelId,omitempty"`
	Limit      int      `json:"limit,omitempty"`
	Lang       string   `json:"lang,omitempty"`
	Text       bool     `json:"text,omitempty"`
}

type YouTubeTranscriptParams added in v0.1.4 

type YouTubeTranscriptParams struct {
	Url       string
	VideoId   string
	Text      bool
	ChunkSize int
	Lang      string
}

type YouTubeTranscriptResult added in v0.1.4 

type YouTubeTranscriptResult struct {
	Content        []TranscriptContent `json:"content"`
	Lang           string              `json:"lang"`
	AvailableLangs []string            `json:"availableLangs"`
}

type YouTubeTranscriptTranslateParams added in v0.1.4 

type YouTubeTranscriptTranslateParams struct {
	Url       string
	VideoId   string
	Text      bool
	ChunkSize int
	Lang      string
}

type YouTubeTranscriptTranslateResult added in v0.1.4 

type YouTubeTranscriptTranslateResult struct {
	Content []TranscriptContent `json:"content"`
	Lang    string              `json:"lang"`
}

type YouTubeVideo added in v0.1.4 

type YouTubeVideo struct {
	Id                  string              `json:"id"`
	Title               string              `json:"title"`
	Description         string              `json:"description"`
	Duration            int                 `json:"duration"`
	Channel             YouTubeVideoChannel `json:"channel"`
	Tags                []string            `json:"tags"`
	Thumbnail           string              `json:"thumbnail"`
	UploadDate          *string             `json:"uploadDate"`
	ViewCount           *int                `json:"viewCount"`
	LikeCount           *int                `json:"likeCount"`
	TranscriptLanguages []string            `json:"transcriptLanguages"`
}

type YouTubeVideoBatchParams added in v0.1.4 

type YouTubeVideoBatchParams struct {
	VideoIds   []string `json:"videoIds,omitempty"`
	PlaylistId string   `json:"playlistId,omitempty"`
	ChannelId  string   `json:"channelId,omitempty"`
	Limit      int      `json:"limit,omitempty"`
}

type YouTubeVideoChannel added in v0.1.4 

type YouTubeVideoChannel struct {
	Id   string `json:"id"`
	Name string `json:"name"`
}

Source Files

View all Source files

Directories

Path Synopsis

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.