Metadata-Version: 2.4
Name: sdta
Version: 0.1.0
Summary: CLI and Python client for the US State Department SDTA Affairs Data API
License: MIT
Project-URL: Homepage, https://github.com/Aureum01/sdta
Project-URL: Repository, https://github.com/Aureum01/sdta
Keywords: travel,advisory,state-department,sdta,risk,intelligence
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27

# sdta

**Python CLI and client for the US State Department SDTA Affairs Data API.**

Query live travel advisories, full country travel information, and field-level data — straight from the official State Department source, no key required.

---

## Install

```bash
pip install sdta
```

Or from source:

```bash
git clone https://github.com/Aureum01/sdta
cd sdta
pip install -e .
```

---

## CLI

### `advisory` — Travel advisory level for a country

```bash
sdta advisory AR
sdta advisory France
sdta advisory MX --json
```

Output:

```
Argentina (AR)
Level 2 — Exercise Increased Caution

Exercise increased caution in Argentina due to crime.

Last Updated: March 11, 2025
```

---

### `advisories` — All current advisories

```bash
sdta advisories
sdta advisories --level 4          # Do Not Travel countries only
sdta advisories --level 3          # Reconsider Travel
sdta advisories --level 4 --json
```

Sorted highest-risk first. Level meanings:

| Level | Label |
|-------|-------|
| 1 | Normal |
| 2 | Exercise Increased Caution |
| 3 | Reconsider Travel |
| 4 | Do Not Travel |

---

### `info` — Full travel information for a country

```bash
sdta info MX                                      # all sections, formatted
sdta info MX --field safety_and_security          # single section, plain text
sdta info MX --json                               # full record as JSON
```

Available `--field` values:

```
destination_description
entry_exit_requirements
health
local_laws_and_special_circumstances
safety_and_security
travel_embassyAndConsulate
travel_transportation
```

---

### `field` — Single field, targeted fetch

Uses the per-field endpoint — lighter than fetching the full record when you only need one section.

```bash
sdta field AR health
sdta field AR health --html         # raw HTML
sdta field AR health --json         # both html + text variants
```

---

### `debug` — Raw API response

Prints the raw JSON from the API. Useful for inspecting the response shape or diagnosing data issues.

```bash
sdta debug FR
```

---

## Python API

All modules are usable directly without the CLI.

### Advisory for a single country

```python
from state_department.travel_advisory_by_country import fetch

advisory = fetch("AR")
print(advisory.country_name)       # Argentina
print(advisory.advisory_level)     # 2
print(advisory.advisory_message)   # Exercise increased caution...
```

### All advisories

```python
from state_department.travel_advisories_all import fetch

advisories = fetch()
level4 = [a for a in advisories if a.advisory_level == 4]
```

### Full country travel info

```python
from state_department.country_travel_info_by_country import fetch, CountryTravelInfo

info: CountryTravelInfo = fetch("MX")
print(info.safety_and_security_text)
print(info.health_text)
print(info.entry_exit_requirements_text)
```

### Single field

```python
from state_department.country_travel_info_field import fetch, FieldResult

result: FieldResult = fetch("AR", "health")
print(result.text)    # plain text
print(result.html)    # raw HTML
```

---

## Data Source

All data is fetched live from the **US State Department SDTA Affairs Data API**:

```
https://cadataapi.state.gov/api/
```

No API key required. No rate limits documented. Data reflects the live State Department website.

Country codes used throughout are the State Department's internal 2-letter tags (mostly matching ISO 3166-1 alpha-2, with some exceptions). See `state_department/state_dept_client.py` for the full list.

---

## Modules

| Module | Endpoint | Description |
|--------|----------|-------------|
| `travel_advisory_by_country` | `/api/TravelAdvisory/{tag}` | Advisory level + message for one country |
| `travel_advisories_all` | `/api/TravelAdvisory` | All current advisories |
| `country_travel_info_by_country` | `/api/CountryTravelInformation/{tag}` | Full travel info record |
| `country_travel_info_field` | `/api/CountryTravelInformation/{tag}/{field}` | Single field from a travel info record |
| `state_dept_client` | — | Shared HTTP client, country code utilities |
| `debug_response` | — | Raw response dump for any endpoint |

---

## License

MIT
