Skip to content

quickstart.mdx

Latest commit

 

History

History
301 lines (244 loc) · 7.24 KB

quickstart.mdx

File metadata and controls

301 lines (244 loc) · 7.24 KB
Raw
title Quickstart
description Get started with the Evoteli in 30 minutes

Overview

This quickstart will guide you through:

  1. Obtaining API credentials
  2. Querying your first signals
  3. Creating an alert
  4. Exploring the dashboard

Prerequisites: You need a Evoteli account with at least one active site or parcel.

Step 1: Obtain API Credentials

Log in to your account at [https://portal.evoteli.com](https://portal.evoteli.com) - Go to **Settings > API Keys** - Click **Create New Client** - Save your `client_id` and `client_secret` (shown only once) Verify your credentials work: 
```bash
curl -X POST https://auth.evoteli.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
```

You should receive an `access_token`.

Step 2: Install SDK (Optional)

pip install geointel-sdk
npm install @geointel/sdk
go get github.com/geointel/sdk-go

Step 3: Query Your First Signals

Using Python SDK

from geointel import Client
import os

# Initialize client
client = Client(
    client_id=os.getenv("GEOINTEL_CLIENT_ID"),
    client_secret=os.getenv("GEOINTEL_CLIENT_SECRET")
)

# Query occupancy for last 24 hours
response = client.signals.query(
    site_id="YOUR_SITE_ID",  # Replace with your site ID
    metrics=["occupancy", "queue_len"],
    time_from="2025-11-05T00:00:00Z",
    time_to="2025-11-06T00:00:00Z",
    rollup="15m"
)

# Print results
for row in response.rows:
    print(f"{row.ts}: {row.metric}={row.value} (quality: {row.quality_score:.2f})")

Using cURL

# Get access token
TOKEN=$(curl -s -X POST https://auth.evoteli.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  | jq -r .access_token)

# Query signals
curl -X POST https://api.evoteli.com/v1/signals:query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "YOUR_SITE_ID",
    "metrics": ["occupancy"],
    "time_from": "2025-11-05T00:00:00Z",
    "time_to": "2025-11-06T00:00:00Z",
    "rollup": "1h"
  }'

Step 4: Create Your First Alert

Objective: Alert when drive-thru queue exceeds 7 vehicles for 10+ minutes.

alert = client.alerts.create(
    channel="slack",  # or "email", "webhook", "teams"
    title="Queue Breach - YOUR_SITE_ID",
    condition={
        "type": "threshold",
        "site_id": "YOUR_SITE_ID",
        "metric": "queue_len",
        "operator": "gt",
        "value": 7,
        "duration_min": 10
    },
    payload={
        "webhook_url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
        "channel": "#ops-alerts"
    }
)

print(f"Alert created: {alert.alert_id}")

Step 5: Explore the Dashboard

Dashboards are available in Grafana or Looker depending on your deployment.

Pre-built Dashboards

  1. LotWatch Overview

    • Real-time occupancy and queue length
    • Hourly turnover rates
    • Service time percentiles (p50/p95)

  2. Network Benchmarks

    • Competitor lunch index
    • Week-over-week traffic trends
    • Site rankings by occupancy

  3. Quality Monitoring

    • Average quality score by site
    • Low-quality metric counts
    • Quality score distribution

Access: https://dashboards.evoteli.com

Step 6: Try Advanced Features

Export Audience (HomeScope)

Objective: Find solar-qualified leads.

job = client.audiences.export(
    name="Solar Qualified Leads",
    filters={
        "south_facing_area_gt": 300,
        "roof_age_band_gte": 12,
        "shade_index_lt": 0.3,
        "utility_rebate_eligible": True
    },
    destination="gads_customer_match"
)

print(f"Export job: {job.job_id}, estimated count: {job.estimated_count}")

# Wait for completion
completed = client.audiences.wait_for_export(job.job_id)
print(f"Download: {completed.download_url}")

Trigger Earth Engine Analysis

Objective: Compute solar insolation for a parcel.

job = client.earthengine.task(
    task_id="insolation_roof",
    polygon_id="YOUR_PARCEL_ID"
)

result = client.earthengine.wait_for_task(job.job_id)
print(f"Insolation: {result.insolation_annual} kWh/m²/year")

Common Tasks

```python sites = client.sites.list() for site in sites: print(f"{site.site_id}: {site.name} ({site.brand})") ``` ```python metrics = client.metrics.list(site_id="YOUR_SITE_ID") for metric in metrics: print(f"{metric.metric}: {metric.last_updated}") ``` ```python provenance = client.provenance.get(metric_id="metric-20251106-001") print(f"Source: {provenance.sources[0].id}") print(f"Model: {provenance.model.name} v{provenance.model.version}") ``` ```python alerts = client.alerts.list(status="active") for alert in alerts: print(f"{alert.alert_id}: {alert.title} (triggered {alert.trigger_count}x)") ```

Next Steps

Explore all API endpoints and parameters Understand the platform architecture Deep dive into commercial analytics Learn about residential intelligence

Troubleshooting

- Check that your `client_id` and `client_secret` are correct - Verify your token hasn't expired (1 hour TTL) - Refresh your token by requesting a new one - Verify your `site_id` or `polygon_id` is correct - Check that metrics are available for your time range - Ensure your account has access to the requested site - Review quality flags: `client.provenance.get(metric_id).quality.flags` - Check for camera occlusion or calibration issues - Contact support if quality remains low - Wait for the `retry_after` duration (see response header) - Reduce request frequency or upgrade your tier - Use rollups (`15m`, `1h`) instead of raw events

Support