Metadata-Version: 2.1
Name: serp-cli
Version: 2026.4.5.1
Summary: CLI tool for Google SERP (Search Engine Results) via AceDataCloud API
Project-URL: Homepage, https://github.com/AceDataCloud/SerpCli
Project-URL: Repository, https://github.com/AceDataCloud/SerpCli
Project-URL: Issues, https://github.com/AceDataCloud/SerpCli/issues
Project-URL: Changelog, https://github.com/AceDataCloud/SerpCli/blob/main/CHANGELOG.md
Author-email: AceDataCloud <support@acedata.cloud>
Maintainer-email: AceDataCloud <support@acedata.cloud>
License: MIT
License-File: LICENSE
Keywords: acedata,cli,command-line,google,search,serp,web-search
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: all
Requires-Dist: serp-cli[dev,release,test]; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: release
Requires-Dist: build>=1.2.0; extra == 'release'
Requires-Dist: twine>=6.1.0; extra == 'release'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: respx>=0.21.0; extra == 'test'
Description-Content-Type: text/markdown

# SERP CLI

A command-line tool for Google Search (SERP) via the [AceDataCloud](https://platform.acedata.cloud) platform.

## Features

- **Web Search** — Search Google and get structured results (organic, knowledge graph, answer box)
- **Image Search** — Find images with `serp images`
- **News Search** — Get news articles with time filtering
- **Video Search** — Find video content from YouTube and more
- **Places Search** — Find local businesses and places
- **Maps Search** — Search Google Maps for locations
- **Rich Output** — Beautiful terminal formatting with `--json` for scripting
- **Localization** — Country and language support for localized results

## Installation

```bash
pip install serp-cli
```

## Quick Start

```bash
# Set your API token
export ACEDATACLOUD_API_TOKEN=your_token_here

# Web search
serp search "artificial intelligence"

# Image search
serp images "sunset photography"

# News with time filter
serp news "tech news" --time-range qdr:d

# Places search
serp places "coffee shops near Times Square" -c us

# Search with pagination
serp search "python tutorials" -n 20 -p 2

# Get JSON output
serp search "hello world" --json | jq '.organic[0].title'
```

## Commands

| Command | Description |
|---------|-------------|
| `search` | Google web search (all types via `-t`) |
| `images` | Google Image search |
| `news` | Google News search |
| `videos` | Google Video search |
| `places` | Google Places search |
| `maps` | Google Maps search |
| `search-types` | List available search types |
| `time-ranges` | List time range filters |
| `config` | Show current configuration |

## Search Options

| Option | Description |
|--------|-------------|
| `-t`, `--type` | Search type: search, images, news, maps, places, videos |
| `-c`, `--country` | Country code (e.g. us, cn, uk) |
| `-l`, `--language` | Language code (e.g. en, zh-cn, fr) |
| `--time-range` | Time filter: qdr:h (hour), qdr:d (day), qdr:w (week), qdr:m (month) |
| `-n`, `--number` | Number of results per page (default: 10) |
| `-p`, `--page` | Page number for pagination |
| `--json` | Output raw JSON |

## Configuration

| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `ACEDATACLOUD_API_TOKEN` | API authentication token | (required) |
| `ACEDATACLOUD_API_BASE_URL` | API base URL | `https://api.acedata.cloud` |
| `SERP_REQUEST_TIMEOUT` | Request timeout in seconds | `30` |

You can also use a `.env` file or pass `--token` directly.

## Docker

```bash
docker compose run serp-cli search "hello world"
```

## Development

```bash
# Install with dev dependencies
pip install -e ".[all]"

# Run tests
pytest

# Run linter
ruff check .
ruff format --check .
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [AceDataCloud Platform](https://platform.acedata.cloud)
- [API Documentation](https://docs.acedata.cloud)
