Developer Documentation

API reference and integration guide

Home / Developer

📋 In This Guide

Developer Overview

SupplyScout provides a REST API for partners to integrate with SupplyScout's supply tracking and disaster management systems. This guide covers authentication, available endpoints, and integration patterns.

Base URL

https://api.supplyscout.org/v1

API Capabilities

Supply Data

Read current supply availability, report supplies, and search supplies across regions.

Store Information

Access store details, locations, and supply history for authorized locations.

Disaster Events

Retrieve active disasters, resources, and alerts for your region.

Inventory Sync

For verified supplier partners: push real-time inventory updates to SupplyScout.

Authentication

API Keys

All API requests require an API key passed in the authorization header:

Authorization: Bearer YOUR_API_KEY

Getting Your API Key

Contact partnerships@supplyscout.org or admin@supplyscout.org to request API access. Include:

Scopes

API keys support different scopes based on your partnership type:

Scope Capabilities
read:supplies Read supply data (all endpoints)
write:supplies Report supplies and update inventory
read:disasters Read disaster and alert information
admin:disasters Create and manage disasters (admins only)

API Reference

Supplies Endpoints

List Supplies at Store

GET
/stores/{storeId}/supplies

Get current supply availability for a specific store.

Report Supplies

POST
/stores/{storeId}/supplies/report

Submit a supply report (requires write:supplies scope).

Request Body:

{ "supplies": { "ice": "in_stock", "propane": "limited", "gasoline": "out_of_stock" }, "reportedAt": "2024-09-28T15:30:00Z" }

Search Supplies

GET
/supplies/search?q=ice&lat=34.5&lon=-82.1&radius=10

Search for specific supplies near a location. Returns matching stores and supply status.

Store Endpoints

Get Store Details

GET
/stores/{storeId}

Get detailed information about a store.

List Nearby Stores

GET
/stores?lat=34.5&lon=-82.1&radius=10

Get all stores within radius (in km) of coordinates.

Disaster Endpoints

List Active Disasters

GET
/disasters?region=sc

Get active disasters in a region (requires read:disasters scope).

Get Disaster Details

GET
/disasters/{disasterId}

Get detailed information about a specific disaster including resources and alerts.

Integration Guide

Verified Supplier Integration

For retailers with inventory systems, you can push real-time supply data to SupplyScout:

Update Store Inventory

POST
/stores/{storeId}/inventory/sync

Update inventory for verified supplier stores (requires write:supplies scope and partnership agreement).

Request Body:

{ "storeId": "abc-123", "timestamp": "2024-09-28T15:30:00Z", "items": [ { "sku": "ICE-10LB", "name": "Ice (10 lb bag)", "availability": "in_stock", "quantity": 45 }, { "sku": "PROPANE-20LB", "name": "Propane (20 lb)", "availability": "limited", "quantity": 3 } ] }

Implementation Examples

Python Example

import requests API_KEY = "your_api_key_here" BASE_URL = "https://api.supplyscout.org/v1" headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } # Search for ice near coordinates response = requests.get( f"{BASE_URL}/supplies/search", params={"q": "ice", "lat": 34.5, "lon": -82.1, "radius": 10}, headers=headers ) stores = response.json()["stores"] for store in stores: print(f"{store['name']}: {store['supplies']}")

JavaScript Example

const API_KEY = "your_api_key_here"; const BASE_URL = "https://api.supplyscout.org/v1"; async function searchSupplies(item, lat, lon, radius) { const response = await fetch( `${BASE_URL}/supplies/search?q=${item}&lat=${lat}&lon=${lon}&radius=${radius}`, { headers: { "Authorization": `Bearer ${API_KEY}` } } ); return response.json(); } // Usage const results = await searchSupplies("ice", 34.5, -82.1, 10); console.log(results.stores);

Webhooks

Event-Driven Updates

For real-time notifications, you can subscribe to webhooks that fire when certain events occur:

Disaster Declaration

Fires when a new disaster is declared in your region

Supply Update

Fires when supply status changes at your stores (verified suppliers only)

Alert Broadcast

Fires when an admin broadcasts an alert to your region

Webhook Payload

{ "event": "disaster.created", "timestamp": "2024-09-28T15:30:00Z", "data": { "disasterId": "d-123", "title": "Hurricane Helene", "severity": "critical", "affectedRegion": "sc", "resources": [...] } }

Registering Webhooks

Contact our team to register webhook endpoints. Provide:

Rate Limits

API requests are rate limited to prevent abuse:

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1695906600

Error Handling

API errors use standard HTTP status codes:

Code Meaning
400 Bad Request - Check your parameters
401 Unauthorized - Check your API key
403 Forbidden - You don't have permission for this
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limit exceeded

Support & Resources

Need help integrating?

SDK Availability: We maintain SDKs for Python, JavaScript/Node, and Go. Custom SDKs available for partnership integrations.