Developer Documentation

List stores near a geographic location. Returns store details with the most recent supply reports.

Parameters

Example Request

curl -H "Authorization: Bearer sk_live_..." \
  "https://api.supplyscout.org/v1/stores?lat=29.7604&lng=-95.3698&radius=5&limit=10"

Example Response

{
  "data": [
    {
      "id": "store_8f3a2b",
      "name": "H-E-B Montrose",
      "type": "grocery",
      "lat": 29.7504,
      "lng": -95.3905,
      "address": "1701 W Alabama St, Houston, TX 77098",
      "distance_miles": 1.3,
      "latest_reports": [
        {
          "supply_type": "ice",
          "status": "in_stock",
          "reported_at": "2026-02-16T14:32:00Z"
        }
      ]
    }
  ],
  "meta": {
    "total": 47,
    "limit": 10,
    "offset": 0
  }
}

Retrieve detailed information about a specific store, including all recent supply reports and operating status.

Example Request

curl -H "Authorization: Bearer sk_live_..." \
  "https://api.supplyscout.org/v1/stores/store_8f3a2b"

Example Response

{
  "data": {
    "id": "store_8f3a2b",
    "name": "H-E-B Montrose",
    "type": "grocery",
    "lat": 29.7504,
    "lng": -95.3905,
    "address": "1701 W Alabama St, Houston, TX 77098",
    "status": "open",
    "status_updated_at": "2026-02-16T10:15:00Z",
    "reports": [
      {
        "id": "rpt_a1b2c3",
        "supply_type": "ice",
        "status": "in_stock",
        "reported_at": "2026-02-16T14:32:00Z"
      },
      {
        "id": "rpt_d4e5f6",
        "supply_type": "propane",
        "status": "low",
        "reported_at": "2026-02-16T13:10:00Z"
      }
    ]
  }
}

List supply reports, optionally filtered by store, supply type, or geographic area.

Parameters

Example Request

curl -H "Authorization: Bearer sk_live_..." \
  "https://api.supplyscout.org/v1/supply-reports?supply_type=ice&lat=29.76&lng=-95.37&radius=10"

Example Response

{
  "data": [
    {
      "id": "rpt_a1b2c3",
      "store_id": "store_8f3a2b",
      "store_name": "H-E-B Montrose",
      "supply_type": "ice",
      "status": "in_stock",
      "reported_at": "2026-02-16T14:32:00Z"
    }
  ],
  "meta": {
    "total": 128,
    "limit": 50,
    "offset": 0
  }
}

Submit a new supply report. Requires write permission on your API key.

Request Body (JSON)

Example Request

curl -X POST \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"store_id":"store_8f3a2b","supply_type":"ice","status":"in_stock"}' \
  "https://api.supplyscout.org/v1/supply-reports"

Example Response

{
  "data": {
    "id": "rpt_x7y8z9",
    "store_id": "store_8f3a2b",
    "supply_type": "ice",
    "status": "in_stock",
    "reported_at": "2026-02-16T15:45:00Z"
  }
}

List all available supply categories and their display metadata.

Example Request

curl -H "Authorization: Bearer sk_live_..." \
  "https://api.supplyscout.org/v1/supply-types"

Example Response

{
  "data": [
    { "id": "ice", "label": "Ice", "emoji": "🧊" },
    { "id": "propane", "label": "Propane", "emoji": "🔥" },
    { "id": "gasoline", "label": "Gasoline", "emoji": "⛽" },
    { "id": "water", "label": "Water", "emoji": "💧" },
    { "id": "batteries", "label": "Batteries", "emoji": "🔋" },
    { "id": "generators", "label": "Generators", "emoji": "⚡" },
    { "id": "groceries", "label": "Groceries", "emoji": "🛒" },
    { "id": "first_aid", "label": "First Aid", "emoji": "🩹" },
    { "id": "tarps", "label": "Tarps", "emoji": "🧱" },
    { "id": "plywood", "label": "Plywood", "emoji": "🪵" }
  ]
}

Retrieve active disaster alerts for a geographic region.

Parameters

Example Request

curl -H "Authorization: Bearer sk_live_..." \
  "https://api.supplyscout.org/v1/alerts?lat=29.76&lng=-95.37"

Example Response

{
  "data": [
    {
      "id": "alert_h1k2m3",
      "type": "hurricane",
      "title": "Hurricane Warning — Greater Houston Area",
      "severity": "extreme",
      "description": "Category 3 hurricane expected to make landfall within 24 hours.",
      "affected_area": {
        "center": { "lat": 29.76, "lng": -95.37 },
        "radius_miles": 80
      },
      "issued_at": "2026-02-15T08:00:00Z",
      "expires_at": "2026-02-18T08:00:00Z"
    }
  ]
}

Get the current operating status of a store.

Example Request

curl -H "Authorization: Bearer sk_live_..." \
  "https://api.supplyscout.org/v1/stores/store_8f3a2b/status"

Example Response

{
  "data": {
    "store_id": "store_8f3a2b",
    "status": "open",
    "updated_at": "2026-02-16T10:15:00Z",
    "reported_by_count": 3
  }
}

Report a store's operating status. Requires write permission.

Request Body (JSON)

Example Request

curl -X POST \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"open"}' \
  "https://api.supplyscout.org/v1/stores/store_8f3a2b/status"

Example Response

{
  "data": {
    "store_id": "store_8f3a2b",
    "status": "open",
    "updated_at": "2026-02-16T15:50:00Z"
  }
}