Skip to main content

Install

pip install neariq

Quick start

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.
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

MethodDescription
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

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

csv_text = client.export(include=["competitors", "alerts"], format="csv")
JSON exports return an ExportResult; CSV exports return the raw CSV string.

Custom base URL

client = NearIQ(api_key="niq_live_...", base_url="http://localhost:3000/api/v1")