API_README.md

# NIST Chemical Kinetics API

This application provides both a web interface (Gradio) and a REST API (FastAPI) for searching and analyzing the NIST Chemical Kinetics Database.

## Access Points

- **Web Interface**: `http://localhost:7860/` (or your deployed URL)
- **API Documentation**: `http://localhost:7860/docs` (Swagger UI)
- **Alternative API Docs**: `http://localhost:7860/redoc` (ReDoc)

## API Endpoints

### 1. Root Information
```
GET /
```
Returns basic API information and available endpoints.

**Response:**
```json
{
  "name": "NIST Chemical Kinetics API",
  "version": "1.0.0",
  "endpoints": {
    "/search": "Search NIST kinetics database",
    "/reaction/{url}": "Get detailed reaction information",
    "/thermodynamic/{formula}": "Get thermodynamic data for a compound",
    "/nist-reactions": "Get list of NIST reactions",
    "/docs": "API documentation"
  }
}
```

### 2. Search Reactions
```
POST /search
```
Search the NIST Chemical Kinetics Database.

**Parameters:**
- `query` (required): Search query string (e.g., "CH4", "benzene")
- `filters` (optional): Array of filter objects

**Request Body Example:**
```json
{
  "query": "CH4",
  "filters": [
    {
      "field": "reactants",
      "relation": "contains",
      "value": "CH4"
    }
  ]
}
```

**Response Example:**
```json
{
  "query": "CH4",
  "count": 10,
  "results": [
    {
      "reaction": "CH4 + OH → CH3 + H2O",
      "k_298": "6.3e-15",
      "a": "2.45e-12",
      "n": "0.0",
      "ea": "1710",
      "t_range": "200-500 K",
      "p_range": "0.001-100 atm",
      "bath_gas": "He",
      "url": "https://kinetics.nist.gov/..."
    }
  ]
}
```

### 3. Get Reaction Detail
```
GET /reaction?url={nist_url}
```
Get detailed information for a specific reaction.

**Parameters:**
- `url` (required): NIST reaction URL

**Response Example:**
```json
{
  "reaction": "CH4 + OH → CH3 + H2O",
  "reactants": ["CH4", "OH"],
  "products": ["CH3", "H2O"],
  "rate_data": [
    {
      "k_298": "6.3e-15",
      "a": "2.45e-12",
      "n": "0.0",
      "ea": "1710",
      "t_range": "200-500 K",
      "p_range": "0.001-100 atm",
      "bath_gas": "He",
      "reference": "Atkinson et al., 2004",
      "squib": "2004ATK/BAU8400-8468"
    }
  ]
}
```

### 4. Get Thermodynamic Data
```
GET /thermodynamic/{formula}?database={db_type}
```
Get thermodynamic data for a compound from NIST WebBook.

**Parameters:**
- `formula` (required): Chemical formula or name (e.g., "CH3", "benzene")
- `database` (optional): Database type - "gas-phase", "ion-energetics", or "condensed-phase" (default: "gas-phase")

**Response Example:**
```json
{
  "formula": "CH3",
  "database": "gas-phase",
  "data": [
    {
      "Temperature (K)": 298.15,
      "Cp (J/mol*K)": 38.70,
      "S (J/mol*K)": 194.20,
      "H-H298 (kJ/mol)": 0.0
    }
  ],
  "summary": "# Thermodynamic Data for CH3\n..."
}
```

### 5. Get NIST Reactions List
```
GET /nist-reactions?limit={number}
```
Get a list of reactions from the NIST database.

**Parameters:**
- `limit` (optional): Maximum number of reactions to return (default: 200)

**Response Example:**
```json
{
  "count": 200,
  "reactions": [
    {
      "label": "CH4 + OH → CH3 + H2O",
      "reaction": "CH4 + OH → CH3 + H2O"
    }
  ]
}
```

## Using the API

### cURL Examples

**Search for reactions:**
```bash
curl -X POST "http://localhost:7860/search?query=CH4" \
  -H "Content-Type: application/json"
```

**Get reaction details:**
```bash
curl "http://localhost:7860/reaction?url=https://kinetics.nist.gov/kinetics/Detail?id=1993DEA/SIB4517-4529:4"
```

**Get thermodynamic data:**
```bash
curl "http://localhost:7860/thermodynamic/CH3?database=gas-phase"
```

**Get NIST reactions list:**
```bash
curl "http://localhost:7860/nist-reactions?limit=50"
```

### Python Example

```python
import requests

# Search for reactions
response = requests.post(
    "http://localhost:7860/search",
    params={"query": "CH4"}
)
data = response.json()
print(f"Found {data['count']} reactions")

# Get thermodynamic data
response = requests.get(
    "http://localhost:7860/thermodynamic/benzene",
    params={"database": "gas-phase"}
)
thermo_data = response.json()
print(thermo_data)
```

### JavaScript Example

```javascript
// Search for reactions
fetch('http://localhost:7860/search?query=CH4', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => console.log(`Found ${data.count} reactions`));

// Get thermodynamic data
fetch('http://localhost:7860/thermodynamic/benzene?database=gas-phase')
  .then(response => response.json())
  .then(data => console.log(data));
```

## Running the Application

```bash
# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py
```

The application will start on `http://0.0.0.0:7860` by default. You can change the port by setting the `PORT` environment variable:

```bash
PORT=8000 python app.py
```

## Deployment

For production deployment, consider using:
- **Gunicorn** with Uvicorn workers
- **Docker** for containerization
- **Nginx** as a reverse proxy

Example with Gunicorn:
```bash
gunicorn app:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:7860
```

## License

Please refer to the NIST data usage policies and licensing terms when using this API.