Metadata-Version: 2.4
Name: deepmap-ai
Version: 0.2.0
Summary: DeepMap AI Python SDK - Multi-physics geospatial intelligence API
Home-page: https://github.com/Mljessop/SensorAnalytics
Author: DeepMap AI / MJ Geophysics
Author-email: DeepMap AI / MJ Geophysics <api@deepmapai.com>
License: MIT
Project-URL: Homepage, https://www.deepmapai.com
Project-URL: Documentation, https://api.deepmapai.com/docs
Project-URL: Repository, https://github.com/Mljessop/SensorAnalytics
Keywords: geospatial,risk,earthquake,flood,wildfire,api,deepmap,insurance,climate,georisk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25
Requires-Dist: pydantic>=2.0
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# DeepMap AI Python SDK

Python SDK for the [DeepMap AI API](https://api.deepmapai.com) -- multi-physics geospatial intelligence for insurance underwriting, climate risk, natural hazard disclosure, and infrastructure monitoring.

## Installation

```bash
pip install deepmap-ai
```

## Quick Start

```python
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.

```python
# 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)

```python
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)

```python
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)

```python
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)

```python
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

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

## Utility Methods

```python
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`:

```python
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

```python
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:

```python
# 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

```python
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
