Getting Started

Quickstart Guide

Go from zero to querying physical space data in under 5 minutes. This guide covers account creation, venue setup, hardware connection, and your first query.

TypeScriptPythoncURL
1

Create operator account

Create an operator account using the admin API. This returns a one-time API key — save it immediately.

TypeScript
step-1.ts
const response = await fetch('https://api.guestnetworks.com/api/operators', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Admin-Key': process.env.GN_ADMIN_SECRET!,
  },
  body: JSON.stringify({
    name: 'Acme Hotels',
    email: 'ops@acmehotels.com',
  }),
});

const { operator, api_key } = await response.json();
// Save api_key immediately — it is only shown once
console.log('API Key:', api_key);
Python
step-1.py
import requests

response = requests.post(
    "https://api.guestnetworks.com/api/operators",
    headers={
        "Content-Type": "application/json",
        "X-Admin-Key": os.environ["GN_ADMIN_SECRET"],
    },
    json={
        "name": "Acme Hotels",
        "email": "ops@acmehotels.com",
    },
)

data = response.json()
# Save api_key immediately — it is only shown once
print("API Key:", data["api_key"])
cURL
step-1.sh
curl -X POST https://api.guestnetworks.com/api/operators \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: $GN_ADMIN_SECRET" \
  -d '{
    "name": "Acme Hotels",
    "email": "ops@acmehotels.com"
  }'
2

Generate API key

The API key returned in step 1 is your authentication token. It starts with gn_live_ and uses AES-256-GCM encryption. Include it in the Authorization header for all subsequent requests.

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

// Verify your key works
const status = await fetch('https://api.guestnetworks.com/health', {
  headers,
});
console.log(await status.json());
// → { status: "ok", db: "connected", redis: "connected" }
Python
step-2.py
import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}",
}

# Verify your key works
response = requests.get(
    "https://api.guestnetworks.com/health",
    headers=headers,
)
print(response.json())
# → {"status": "ok", "db": "connected", "redis": "connected"}
cURL
step-2.sh
# Set your API key as an environment variable
export GN_API_KEY="gn_live_sk_..."

# Verify your key works
curl https://api.guestnetworks.com/health \
  -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',
    capacity: 200,
  }),
});

const { 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",
        "capacity": 200,
    },
)

venue_id = venue.json()["venue_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",
    "capacity": 200
  }'
4

Connect hardware

Add a hardware integration to your venue. Each connector type has its own config schema validated with Zod.

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

const { 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={
        "connector_type": "meraki",
        "config": {
            "api_key": os.environ["MERAKI_API_KEY"],
            "org_id": "553998",
        },
    },
)

integration_id = integration.json()["integration_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 '{
    "connector_type": "meraki",
    "config": {
      "api_key": "'$MERAKI_API_KEY'",
      "org_id": "553998"
    }
  }'
5

Ingest first event

Send a connection event to the ingestion endpoint. Events are rate-limited to 100/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({
    event_type: 'device_connected',
    venue_id,
    device_hash: 'test_device_001',
    timestamp: new Date().toISOString(),
    connector_type: 'meraki',
    metadata: {
      signal_strength: -42,
      ssid: 'Guest-WiFi',
    },
  }),
});

console.log(await event.json());
// → { accepted: true }
Python
step-5.py
from datetime import datetime, timezone

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

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

Query data

Use MCP tools or the REST API to query your venue data. 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: { 'X-GN-API-Key': API_KEY },
      },
    }
  )
);

const result = await client.callTool('get_current_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
venues = requests.get(
    "https://api.guestnetworks.com/api/venues",
    headers=headers,
)

for venue in venues.json():
    print(f"{venue['name']}: {venue['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