api

package
v1.10.2 Latest Latest
Warning

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

 Go to latest Published: Mar 8, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package api provides the HTTP API for Google Maps Scraper Pro.

@title Google Maps Scraper Pro API @version 1.0 @description API for scraping Google Maps data asynchronously

@contact.name API Support @contact.url https://github.com/gosom/google-maps-scraper

@license.name MIT @license.url https://opensource.org/licenses/MIT

@host localhost:8080 @BasePath /

@schemes http https

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func KeyAuth 

func KeyAuth(validateKey ValidateKeyFunc) func(http.Handler) http.Handler

KeyAuth middleware validates API keys from Authorization or X-API-Key headers.

func Routes 

func Routes(r chi.Router, appState *AppState)

Routes sets up API routes on the given router.

Types

type AppState 

type AppState struct {
	RQueue *rqueue.Client
	Store  IStore
}

AppState holds dependencies for API handlers.

func NewAppState 

func NewAppState(rqueue *rqueue.Client, store IStore) *AppState

NewAppState creates a new API AppState.

type DeleteJobResponse 

type DeleteJobResponse struct {
	// Status message
	Message string `json:"message" example:"deletion queued"`
}

DeleteJobResponse represents the response after requesting job deletion @Description Response returned after successfully queueing a job for deletion

type ErrorResponse 

type ErrorResponse struct {
	Message string `json:"message" example:"invalid request body"`
}

ErrorResponse represents an error response @Description Error response returned when a request fails

type GmapData 

type GmapData any

GmapData represents Google Maps scrape results data.

type HealthCheckResponse 

type HealthCheckResponse struct {
	Status string `json:"status" example:"ok"`
}

HealthCheckResponse represents a health check response @Description Health check response indicating service status

type IStore 

type IStore interface {
	ValidateAPIKey(ctx context.Context, key string) (keyID int, keyName string, err error)
}

IStore defines the interface for API storage operations.

type JobStatusResponse 

type JobStatusResponse struct {
	// Unique job identifier
	JobID string `json:"job_id" example:"kYzR8xLmNpQvWjX3"`
	// Current job status (pending, running, completed, failed)
	Status string `json:"status" example:"completed"`
	// Search keyword used for this job
	Keyword string `json:"keyword" example:"restaurants in New York"`
	// When the job was created
	CreatedAt time.Time `json:"created_at" example:"2024-01-15T10:30:00Z"`
	// When the job started processing
	StartedAt *time.Time `json:"started_at,omitempty" example:"2024-01-15T10:30:05Z"`
	// When the job completed
	CompletedAt *time.Time `json:"completed_at,omitempty" example:"2024-01-15T10:35:00Z"`
	// Scrape results (array of place data)
	Results GmapData `json:"results,omitempty"`
	// Error message if job failed
	Error string `json:"error,omitempty" example:""`
	// Number of results found
	ResultCount int `json:"result_count" example:"25"`
}

JobStatusResponse represents the status of a scrape job @Description Detailed status of a scrape job including results when completed

type JobSummary 

type JobSummary struct {
	// Unique job identifier (encoded)
	JobID string `json:"job_id" example:"kYzR8xLmNpQvWjX3"`
	// Current job status
	Status string `json:"status" example:"completed"`
	// Search keyword used for this job
	Keyword string `json:"keyword" example:"restaurants in New York"`
	// When the job was created
	CreatedAt time.Time `json:"created_at" example:"2024-01-15T10:30:00Z"`
	// When the job started processing
	StartedAt *time.Time `json:"started_at,omitempty" example:"2024-01-15T10:30:05Z"`
	// When the job completed
	CompletedAt *time.Time `json:"completed_at,omitempty" example:"2024-01-15T10:35:00Z"`
	// Number of results found
	ResultCount int `json:"result_count" example:"25"`
	// Error message if job failed
	Error string `json:"error,omitempty" example:""`
}

JobSummary represents a job without result data @Description Summary of a job without the full result data

type KeyInfo 

type KeyInfo struct {
	ID   int
	Name string
}

KeyInfo represents minimal API key information stored in context.

func KeyFromContext 

func KeyFromContext(ctx context.Context) *KeyInfo

KeyFromContext retrieves the API key info from context.

type ListJobsRequest 

type ListJobsRequest struct {
	// Filter by job state (available, running, completed, cancelled, discarded, pending, retryable, scheduled)
	State string `json:"state,omitempty" example:"completed"`
	// Number of jobs to return (default: 20, max: 100)
	Limit int `json:"limit,omitempty" example:"20"`
	// Cursor for pagination (from previous response)
	Cursor string `json:"cursor,omitempty" example:""`
}

ListJobsRequest represents parameters for listing jobs @Description Query parameters for listing jobs with pagination and filtering

type ListJobsResponse 

type ListJobsResponse struct {
	// List of jobs
	Jobs []JobSummary `json:"jobs"`
	// Cursor for next page (empty if no more results)
	NextCursor string `json:"next_cursor,omitempty" example:"eyJpZCI6MTIzfQ=="`
	// Whether there are more results
	HasMore bool `json:"has_more" example:"true"`
}

ListJobsResponse represents a paginated list of jobs @Description Paginated list of jobs with cursor for next page

type ScrapeRequest 

type ScrapeRequest struct {
	// Search keyword (e.g., "restaurants in New York")
	Keyword string `json:"keyword" example:"restaurants in New York"`
	// Language code for results (default: "en")
	Lang string `json:"lang,omitempty" example:"en"`
	// Maximum depth for pagination (default: 1, max: 100)
	MaxDepth int `json:"max_depth,omitempty" example:"1"`
	// Whether to extract email addresses from websites
	Email bool `json:"email,omitempty" example:"false"`
	// Geographic coordinates in "lat,lon" format
	GeoCoordinates string `json:"geo_coordinates,omitempty" example:"40.7128,-74.0060"`
	// Zoom level for map search (1-21)
	Zoom int `json:"zoom,omitempty" example:"14"`
	// Search radius in kilometers
	Radius float64 `json:"radius,omitempty" example:"5.0"`
	// Use fast mode (stealth HTTP instead of browser)
	FastMode bool `json:"fast_mode,omitempty" example:"false"`
	// Extract additional reviews
	ExtraReviews bool `json:"extra_reviews,omitempty" example:"false"`
	// Job timeout in seconds (1-300, default: 300)
	Timeout int `json:"timeout,omitempty" example:"300"`
}

ScrapeRequest represents a request to scrape Google Maps @Description Request body for submitting a scrape job

func (*ScrapeRequest) SetDefaults 

func (r *ScrapeRequest) SetDefaults()

func (*ScrapeRequest) Validate 

func (r *ScrapeRequest) Validate() error

type ScrapeResponse 

type ScrapeResponse struct {
	// Unique job identifier
	JobID string `json:"job_id" example:"kYzR8xLmNpQvWjX3"`
	// Current job status
	Status string `json:"status" example:"pending"`
}

ScrapeResponse represents the response after submitting a scrape job @Description Response returned after successfully submitting a scrape job

type ValidateKeyFunc 

type ValidateKeyFunc func(ctx context.Context, key string) (keyID int, keyName string, err error)

ValidateKeyFunc is a function that validates an API key and returns key info.

Source Files

View all Source files

Directories

Path Synopsis
Package docs Code generated by swaggo/swag.
 Package docs Code generated by swaggo/swag.

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.