DeepMap AI Python SDK

Python SDK for the DeepMap AI API -- multi-physics geospatial intelligence for insurance underwriting, climate risk, natural hazard disclosure, and infrastructure monitoring.

Installation

pip install deepmap-ai

Quick Start

from deepmap_ai import DeepMapClient

client = DeepMapClient(api_key="your-api-key")

# GeoRisk composite score (insurance underwriting)
risk = client.georisk(lat=40.76, lon=-111.89)
print(risk["composite_score"], risk["risk_level"])

# Search for a company (SEC/EDGAR)
results = client.entity.search("Apple Inc")

# Get company financials
financials = client.entity.financials("0000320193")

Product Endpoints

GeoRisk Score (Flagship)

8-component composite risk score for any lat/lon -- earthquake, volcano, tsunami, seismic site, sinkhole, weather, flood, and landslide.

# Basic score
risk = client.georisk(lat=34.05, lon=-118.24)

# Filter to specific components
risk = client.georisk(lat=34.05, lon=-118.24, components=["earthquake", "wildfire"])

Entity (SEC/EDGAR)

client.entity.search("Tesla")
client.entity.profile("0001318605")
client.entity.filings("0001318605", form_type="10-Q")
client.entity.financials("0001318605")
client.entity.risk("0001318605")
client.entity.demo()          # No API key required
client.entity.health()

Economic (FRED)

client.economic.series("GDP", limit=50)
client.economic.series("UNRATE", start="2020-01-01", end="2024-01-01")
client.economic.snapshot()
client.economic.forecast("GDP", horizon=12)
client.economic.list_series()
client.economic.health()

Weather (NWS/NOAA)

client.weather.current("KJFK")
client.weather.forecast(lat=40.7128, lon=-74.0060)
client.weather.alerts("TX")
client.weather.historical("KJFK")
client.weather.analysis(station_id="KJFK")
client.weather.analysis(lat=40.7128, lon=-74.0060)
client.weather.stations()
client.weather.health()

Environmental (EPA)

client.environmental.search_facilities("chemical plant Texas")
client.environmental.facility("110000000001")
client.environmental.compliance("110000000001")
client.environmental.releases("110000000001")
client.environmental.risk("110000000001")
client.environmental.health()

Cross-Connector Query

result = client.query(
    "What is Apple's revenue compared to GDP growth?",
    connectors=["entity", "economic"]
)

Utility Methods

client.connectors()   # List available connectors
client.pricing()      # View pricing table
client.health()       # Overall API health

Async Usage

Every method has an async counterpart prefixed with a:

import asyncio
from deepmap_ai import DeepMapClient

async def main():
    async with DeepMapClient(api_key="your-api-key") as client:
        risk = await client.ageorisk(lat=40.76, lon=-111.89)
        results = await client.entity.asearch("Microsoft")
        snapshot = await client.economic.asnapshot()
        weather = await client.weather.acurrent("KJFK")
        print(risk, results)

asyncio.run(main())

Error Handling

from deepmap_ai import (
    DeepMapClient,
    DeepMapAPIError,
    AuthenticationError,
    RateLimitError,
    QuotaExceededError,
    NotFoundError,
)

client = DeepMapClient(api_key="your-api-key")

try:
    result = client.georisk(lat=40.76, lon=-111.89)
except AuthenticationError:
    print("Invalid or missing API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except QuotaExceededError:
    print("Monthly quota exhausted -- upgrade your plan")
except NotFoundError:
    print("Resource not found")
except DeepMapAPIError as e:
    print(f"API error {e.status_code}: {e.message}")

Backward Compatibility

If you are migrating from publicdata-oracle, the old import names still work:

# Old style (still supported)
from publicdata_oracle import OracleClient
client = OracleClient(api_key="your-key")

# New style (recommended)
from deepmap_ai import DeepMapClient
client = DeepMapClient(api_key="your-key")

OracleClient is an alias for DeepMapClient -- they are the same class.

Configuration

client = DeepMapClient(
    api_key="your-api-key",
    base_url="https://custom-endpoint.example.com",  # Custom API endpoint
    timeout=60.0,                                      # Request timeout in seconds
)

License

MIT