> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neariq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Python

> Official Python SDK for the NearIQ API.

## Install

```bash theme={null}
pip install neariq
```

## Quick start

```python theme={null}
from neariq import NearIQ

with NearIQ(api_key="niq_live_...") as client:
    business = client.me()
    print(f"{business.name}: {business.rating} stars")

    competitors = client.competitors()
    for competitor in competitors:
        print(competitor.name, competitor.rating, competitor.momentum_trend)

    report = client.create_report(lenses=["reputation", "growth"])
    print(report.headline)
```

## Authentication

Create an API key in Settings > API. The SDK sends it with the `X-NearIQ-Key` header.

```python theme={null}
import os
from neariq import NearIQ

client = NearIQ(api_key=os.environ["NEARIQ_API_KEY"])
```

API access requires a plan with public API access and the scopes required by the endpoint you call.

## Common methods

| Method                                                | Description                                      |
| ----------------------------------------------------- | ------------------------------------------------ |
| `client.me()`                                         | Active business profile                          |
| `client.competitors()`                                | Tracked competitors                              |
| `client.create_competitor(...)`                       | Add or reactivate a tracked competitor           |
| `client.competitor(id)`                               | Single competitor detail                         |
| `client.competitor_snapshots(id)`                     | Historical competitor snapshots                  |
| `client.competitor_reviews(id)`                       | Cached competitor reviews and sentiment          |
| `client.alerts()`                                     | Recent alerts                                    |
| `client.dismiss_alert(id)`                            | Mark an alert as read                            |
| `client.snapshots()`                                  | Own-business snapshot history                    |
| `client.own_reviews()`                                | Own-business reviews                             |
| `client.response_templates()`                         | Review response templates                        |
| `client.reviews(...)`                                 | Search cached reviews across tracked competitors |
| `client.rank_checks()`                                | Local rank tracker checks                        |
| `client.content_history()`                            | Content Studio history                           |
| `client.generate_content(...)`                        | Generate Content Studio output                   |
| `client.agents()`                                     | AI agents                                        |
| `client.create_agent(...)`                            | Create an AI agent                               |
| `client.update_agent(id, ...)`                        | Update an AI agent                               |
| `client.run_agent(id)`                                | Queue an agent run                               |
| `client.reports()`                                    | Intelligence report history                      |
| `client.report(report_id)`                            | Single stored intelligence report                |
| `client.create_report(...)`                           | Generate an intelligence report                  |
| `client.export_report(report_id)`                     | Create a PDF export record for a report          |
| `client.export(...)`                                  | Export account data as JSON or CSV               |
| `client.export_all(...)`                              | ZIP export with JSON, CSV, XLSX, and metadata    |
| `client.usage()`                                      | API usage statistics                             |
| `client.chat(message, context)`                       | Send a message to the AI assistant               |
| `client.ai_visibility(days)`                          | AI search visibility scores                      |
| `client.behavioral_signals()`                         | Behavioral engagement signals                    |
| `client.gap_analysis()`                               | Competitive gap analysis                         |
| `client.site_audit()`                                 | SEO site audit results                           |
| `client.ads(platform)`                                | Ad campaign drafts                               |
| `client.social_posts()`                               | Social post history                              |
| `client.leads()`                                      | Lead scores and pipeline                         |
| `client.review_requests()`                            | Review request history                           |
| `client.voice_clones()`                               | Voice clone inventory                            |
| `client.videos(limit, status)`                        | Video generation history                         |
| `client.generate_image(prompt, preset, style)`        | Generate an AI image                             |
| `client.create_video(prompt, duration, aspect_ratio)` | Create a video generation job                    |
| `client.citations()`                                  | Citation and listing status                      |
| `client.brand_mentions()`                             | Brand mention tracking                           |
| `client.gbp_health()`                                 | Google Business Profile health                   |
| `client.gbp_insights(days)`                           | GBP performance insights                         |
| `client.leaderboard(city, sort)`                      | Market leaderboard data                          |
| `client.market(period)`                               | Market intelligence trends                       |
| `client.market_density()`                             | Market density metrics                           |
| `client.market_saturation()`                          | Market saturation metrics                        |
| `client.market_leaders()`                             | Market leader rows                               |
| `client.market_signals()`                             | Market signals                                   |
| `client.market_trends()`                              | Market trend records                             |
| `client.market_projections()`                         | Market projections                               |
| `client.webhooks()`                                   | Webhook endpoints                                |
| `client.create_webhook(...)`                          | Register a webhook                               |
| `client.update_webhook(id, ...)`                      | Update a webhook                                 |
| `client.delete_webhook(id)`                           | Delete a webhook                                 |
| `client.keyword_suggestions()`                        | Keyword research suggestions                     |
| `client.hiring_signals()`                             | Competitor hiring activity                       |
| `client.review_requests()`                            | Review request history                           |
| `client.send_review_request(...)`                     | Send a review request                            |
| `client.create_social_post(...)`                      | Create a social post                             |
| `client.listing_sync()`                               | Directory listing sync                           |
| `client.conversations()`                              | Messaging conversations                          |
| `client.publish_targets()`                            | Publishing targets                               |
| `client.charts(...)`                                  | Chart data                                       |
| `client.create_chart_embed(...)`                      | Signed embeddable chart URL                      |
| `client.tables()`                                     | Tabular dashboard data                           |
| `client.create_video(prompt, duration, aspect_ratio)` | Create a video generation job                    |

## Error handling

```python theme={null}
from neariq import NearIQ, NearIQError

client = NearIQ(api_key="niq_live_...")

try:
    client.me()
except NearIQError as exc:
    print(exc.status_code, exc.body)
```

## CSV export

```python theme={null}
csv_text = client.export(include=["competitors", "alerts"], format="csv")
```

JSON exports return an `ExportResult`; CSV exports return the raw CSV string.

## Custom base URL

```python theme={null}
client = NearIQ(api_key="niq_live_...", base_url="http://localhost:3000/api/v1")
```