Getting Started

Quickstart Guide

Go from zero to querying physical space data in under 5 minutes. This guide covers signing up for your API key, venue setup, hardware connection, and your first query.

TypeScriptPythoncURL
1

Sign up and get your API key

Create a free account at the portal signup page to get your API key instantly — no credit card required. The key is shown once, starts with gn_live_, and is your authentication token for every request. There is no admin step: the admin API (POST /api/operators with X-Admin-Key) is platform-internal and not available to customers.

TypeScript
step-1.ts
// 1. Open https://www.guestnetworks.com/signup in your browser
// 2. Enter your name + email and click "Generate API Key"
// 3. Copy your key — it is shown only once. It looks like:
//      gn_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx
//
// Store it in your environment, never in source control:
const API_KEY = process.env.GN_API_KEY!; // gn_live_sk_...
Python
step-1.py
# 1. Open https://www.guestnetworks.com/signup in your browser
# 2. Enter your name + email and click "Generate API Key"
# 3. Copy your key — it is shown only once. It looks like:
#      gn_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx
#
# Store it in your environment, never in source control:
import os

API_KEY = os.environ["GN_API_KEY"]  # gn_live_sk_...
cURL
step-1.sh
# 1. Open https://www.guestnetworks.com/signup in your browser
# 2. Enter your name + email and click "Generate API Key"
# 3. Copy your key — it is shown only once (gn_live_sk_...)

# Store it as an environment variable for the steps below:
export GN_API_KEY="gn_live_sk_..."
2

Authenticate your requests

Send your API key as a Bearer token in the Authorization header on every REST request. The REST API and ingest endpoint live at https://api.guestnetworks.com. The /health endpoint is public, so it is the quickest way to confirm the service is reachable before you authenticate.

TypeScript
step-2.ts
// All REST + ingest requests use Bearer token authentication
const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${API_KEY}`,
};

// /health is public — no auth needed — use it to check connectivity
const status = await fetch('https://api.guestnetworks.com/health');
console.log(await status.json());
// → { status: "healthy", version: "...", checks: { db: {...}, redis: {...} } }

// Authenticated call: list your venues (empty on a new account)
const venues = await fetch('https://api.guestnetworks.com/api/venues', {
  headers,
});
console.log(await venues.json());
Python
step-2.py
import requests

# All REST + ingest requests use Bearer token authentication
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}",
}

# /health is public — no auth needed — use it to check connectivity
status = requests.get("https://api.guestnetworks.com/health")
print(status.json())
# → {"status": "healthy", "version": "...", "checks": {...}}

# Authenticated call: list your venues (empty on a new account)
venues = requests.get(
    "https://api.guestnetworks.com/api/venues",
    headers=headers,
)
print(venues.json())
cURL
step-2.sh
# /health is public — no auth needed
curl https://api.guestnetworks.com/health

# Authenticated call: list your venues (empty on a new account)
curl https://api.guestnetworks.com/api/venues \
  -H "Authorization: Bearer $GN_API_KEY"
3

Add venue

Register a venue. Venues are the top-level entity in GuestNetworks — every zone, integration, and event belongs to a venue.

TypeScript
step-3.ts
const venue = await fetch('https://api.guestnetworks.com/api/venues', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Downtown Hotel',
    address: '123 Main St, New York, NY',
    timezone: 'America/New_York',
    hardware_type: 'meraki',
  }),
});

// The venue is returned with its generated UUID as "id"
const { id: venue_id } = await venue.json();
console.log('Venue ID:', venue_id);
Python
step-3.py
venue = requests.post(
    "https://api.guestnetworks.com/api/venues",
    headers=headers,
    json={
        "name": "Downtown Hotel",
        "address": "123 Main St, New York, NY",
        "timezone": "America/New_York",
        "hardware_type": "meraki",
    },
)

# The venue is returned with its generated UUID as "id"
venue_id = venue.json()["id"]
print("Venue ID:", venue_id)
cURL
step-3.sh
curl -X POST https://api.guestnetworks.com/api/venues \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GN_API_KEY" \
  -d '{
    "name": "Downtown Hotel",
    "address": "123 Main St, New York, NY",
    "timezone": "America/New_York",
    "hardware_type": "meraki"
  }'
# Response includes the venue "id" — save it as $VENUE_ID for the next steps
4

Connect hardware

Add a hardware integration to your venue. The request body is the connector config itself, discriminated by a "type" field. Supported types: meraki, unifi, mywifi, aruba, square, density, verkada — each with its own Zod-validated fields. Credentials are encrypted at rest with AES-256-GCM.

TypeScript
step-4.ts
const integration = await fetch(
  `https://api.guestnetworks.com/api/venues/${venue_id}/integrations`,
  {
    method: 'POST',
    headers,
    body: JSON.stringify({
      type: 'meraki',
      api_key: process.env.MERAKI_API_KEY!,
      org_id: '553998',
    }),
  }
);

// The integration is returned with its generated UUID as "id"
const { id: integration_id } = await integration.json();
console.log('Integration ID:', integration_id);
Python
step-4.py
integration = requests.post(
    f"https://api.guestnetworks.com/api/venues/{venue_id}/integrations",
    headers=headers,
    json={
        "type": "meraki",
        "api_key": os.environ["MERAKI_API_KEY"],
        "org_id": "553998",
    },
)

# The integration is returned with its generated UUID as "id"
integration_id = integration.json()["id"]
print("Integration ID:", integration_id)
cURL
step-4.sh
curl -X POST "https://api.guestnetworks.com/api/venues/$VENUE_ID/integrations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GN_API_KEY" \
  -d '{
    "type": "meraki",
    "api_key": "'$MERAKI_API_KEY'",
    "org_id": "553998"
  }'
5

Ingest first event

Send one or more events to the ingestion endpoint. The body groups events under a single venue_id and connector_type; each event has a type, an ISO-8601 timestamp, and a free-form payload (device_hash, zone_id, count, and metrics are read from the payload). Ingest is rate-limited to 100 requests/min per operator and processed through the real-time pipeline.

TypeScript
step-5.ts
const event = await fetch('https://api.guestnetworks.com/ingest', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    venue_id,
    connector_type: 'meraki',
    events: [
      {
        type: 'device_connected',
        timestamp: new Date().toISOString(),
        payload: {
          device_hash: 'test_device_001',
          metrics: { signal_strength: -42, ssid: 'Guest-WiFi' },
        },
      },
    ],
  }),
});

console.log(await event.json());
// → { accepted: 1, rejected: 0, errors: [] }
Python
step-5.py
from datetime import datetime, timezone

event = requests.post(
    "https://api.guestnetworks.com/ingest",
    headers=headers,
    json={
        "venue_id": venue_id,
        "connector_type": "meraki",
        "events": [
            {
                "type": "device_connected",
                "timestamp": datetime.now(timezone.utc).isoformat(),
                "payload": {
                    "device_hash": "test_device_001",
                    "metrics": {"signal_strength": -42, "ssid": "Guest-WiFi"},
                },
            },
        ],
    },
)

print(event.json())
# → {"accepted": 1, "rejected": 0, "errors": []}
cURL
step-5.sh
curl -X POST https://api.guestnetworks.com/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GN_API_KEY" \
  -d '{
    "venue_id": "'$VENUE_ID'",
    "connector_type": "meraki",
    "events": [
      {
        "type": "device_connected",
        "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%S.000Z)'",
        "payload": {
          "device_hash": "test_device_001",
          "metrics": { "signal_strength": -42, "ssid": "Guest-WiFi" }
        }
      }
    ]
  }'
6

Query data

Use the MCP tools or the REST API to query your venue data. The MCP endpoint (/mcp) authenticates with the same Authorization: Bearer header as the REST API — one key, one header everywhere. Here is how to get current occupancy via the MCP protocol.

TypeScript
step-6.ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from
  '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'my-agent', version: '1.0' });

await client.connect(
  new StreamableHTTPClientTransport(
    new URL('https://api.guestnetworks.com/mcp'),
    {
      requestInit: {
        headers: { 'Authorization': `Bearer ${API_KEY}` },
      },
    }
  )
);

const result = await client.callTool('get_occupancy', {
  venue_id,
});

console.log(JSON.parse(result.content[0].text));
// → { occupancy: { current: 47, capacity: 200, utilization: 0.235 } }
Python
step-6.py
# Using the REST API directly
res = requests.get(
    "https://api.guestnetworks.com/api/venues",
    headers=headers,
)

# Response shape: { "venues": [...], "total": N, "limit": 50, "offset": 0 }
for venue in res.json()["venues"]:
    print(f"{venue['name']}: {venue['id']}")
cURL
step-6.sh
# Query all your venues
curl https://api.guestnetworks.com/api/venues \
  -H "Authorization: Bearer $GN_API_KEY"

# Query venue details
curl "https://api.guestnetworks.com/api/venues/$VENUE_ID" \
  -H "Authorization: Bearer $GN_API_KEY"

Next steps