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:

{
  "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:

{
  "query": "CH4",
  "filters": [
    {
      "field": "reactants",
      "relation": "contains",
      "value": "CH4"
    }
  ]
}

Response Example:

{
  "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:

{
  "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:

{
  "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:

{
  "count": 200,
  "reactions": [
    {
      "label": "CH4 + OH → CH3 + H2O",
      "reaction": "CH4 + OH → CH3 + H2O"
    }
  ]
}

Using the API

cURL Examples

Search for reactions:

curl -X POST "http://localhost:7860/search?query=CH4" \
  -H "Content-Type: application/json"

Get reaction details:

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

Get thermodynamic data:

curl "http://localhost:7860/thermodynamic/CH3?database=gas-phase"

Get NIST reactions list:

curl "http://localhost:7860/nist-reactions?limit=50"

Python Example

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

// 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

# 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:

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:

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.