bible-app/RAPIDAPI_SETUP.md

# RapidAPI Complete Study Bible Integration Setup

This guide explains how to set up and use the RapidAPI Complete Study Bible API integration to enhance popup cards for words in the Bible App.

## Overview

The RapidAPI Complete Study Bible API integration adds additional word information to your popup cards, including:
- Strong's numbers
- Enhanced definitions
- Transliterations
- Morphology information
- Cross-references
- Commentaries
- Usage statistics

## Prerequisites

1. **RapidAPI Account**: You need a RapidAPI account (free tier available)
2. **API Key**: Get your API key from the RapidAPI dashboard
3. **API Subscription**: Subscribe to the "Complete Study Bible" API on RapidAPI

## Step 1: Get Your RapidAPI API Key

1. Go to [RapidAPI](https://rapidapi.com/)
2. Sign up or log in to your account
3. Navigate to the [Complete Study Bible API](https://rapidapi.com/teachjesusapp/api/complete-study-bible)
4. Click "Subscribe" and choose a plan (free tier is usually available)
5. Copy your API key from the dashboard

## Step 2: Configure the API Key

Open your browser's developer console (F12) and run:

```javascript
localStorage.setItem('rapidapi.key', 'YOUR_API_KEY_HERE');
localStorage.setItem('rapidapi.host', 'complete-study-bible.p.rapidapi.com');
```

Replace `YOUR_API_KEY_HERE` with your actual RapidAPI API key.

**Note**: The API host is usually `complete-study-bible.p.rapidapi.com`, but check the RapidAPI playground to confirm the exact host name.

## Step 3: Test the API Endpoints

Before integrating, you should test the API endpoints in the RapidAPI playground to understand the response structure:

1. Go to the [API Playground](https://rapidapi.com/teachjesusapp/api/complete-study-bible/playground/apiendpoint_c726eca5-3238-43bb-bee5-c17877e23d92)
2. Test different endpoints to see what data is available
3. Note the endpoint structure and response format

### Common Endpoint Patterns

The integration tries these endpoint patterns automatically:
- `/word/{word}` - Get word definitions
- `/word/{word}/definition` - Get word definitions (alternative)
- `/search?word={word}` - Search for word
- `/definition/{word}` - Get definition (alternative)
- `/words/{word}` - Get word info (alternative)

## Step 4: Update the Integration (if needed)

If the API uses different endpoints than the defaults, you may need to update `rapidapi-study-bible.js`:

1. Open `rapidapi-study-bible.js`
2. Find the `queryRapidAPIWord` function
3. Update the `endpoint` variable to match your API's endpoint structure
4. Update the `parseRapidAPIResponse` function to match your API's response format

## Step 5: Test the Integration

Open your browser console and run:

```javascript
// Test if API is configured
await window.checkRapidAPIAvailability();

// Test with a word
await window.testRapidAPIIntegration('love');

// Or test manually
const wordInfo = await window.getWordInfo('grace');
const enhanced = await window.enhanceWordInfoWithRapidAPI(wordInfo, 'grace', 'John 3:16');
console.log(enhanced);
```

## Step 6: Verify Popup Display

1. Open your Bible App
2. Click on a word to open a popup
3. Look for the "Complete Study Bible" section in the popup
4. Verify that the data is displaying correctly

## Troubleshooting

### API Key Not Working

- Verify your API key is correct: `localStorage.getItem('rapidapi.key')`
- Check that you've subscribed to the API on RapidAPI
- Verify the API host is correct: `localStorage.getItem('rapidapi.host')`

### No Data in Popups

- Check browser console for errors
- Verify API endpoints are correct (test in RapidAPI playground first)
- Update `parseRapidAPIResponse` function to match your API's response format
- Check network tab to see if API requests are being made

### Wrong Data Format

The API response format may differ from what's expected. Update the `parseRapidAPIResponse` function in `rapidapi-study-bible.js` to match your API's actual response structure.

### CORS Issues

If you encounter CORS errors, you may need to:
1. Make API requests through your server (`server.js`) instead of directly from the browser
2. Add CORS headers to your server configuration
3. Use a proxy server

## API Response Format

The integration expects the API to return data in one of these formats:

```javascript
// Format 1: Direct properties
{
  greek: "χάρις",
  greekText: "χάρις",
  hebrew: "חֵן",
  strongs: "G5485",
  definition: "grace, favor",
  transliteration: "charis",
  commentaries: ["Commentary text..."],
  crossReferences: ["John 1:14", "Ephesians 2:8"]
}

// Format 2: Nested structure
{
  data: {
    greek: "χάρις",
    definition: "grace, favor"
  }
}
```

Adjust the `parseRapidAPIResponse` function based on your actual API response.

## Integration with Other APIs

The RapidAPI integration works alongside:
- **Greek WordNet API** - For Greek word definitions
- **Accordance API** - For Accordance Bible Software integration
- **Local dictionaries** - For Strong's numbers and definitions

All data sources are combined in the popup for comprehensive word information.

## Security Notes

- **Never commit your API key to version control**
- Store API keys in localStorage (as shown) or environment variables
- Consider implementing server-side API calls for production apps
- Monitor API usage to avoid exceeding rate limits

## Support

If you encounter issues:
1. Check the browser console for error messages
2. Test the API endpoints directly in RapidAPI playground
3. Verify the API response format matches the parser expectations
4. Review the `rapidapi-study-bible.js` file for integration details

## Next Steps

Once the integration is working:
1. Test with various words to ensure data quality
2. Customize the popup display in `app.js` (look for `rapidAPISection`)
3. Add styling for RapidAPI sections in your CSS file
4. Consider caching API responses to reduce API calls