Church Locator API Documentation

Overview

The Church Locator API provides endpoints for finding, managing, and searching Catholic churches. It supports geospatial searches, user submissions, and administrative management.

Base URL

``` https://api.elbiblio.com/api/churches ```

Authentication

- Public endpoints: `nearby`, `search`, `show`, `stats` - No authentication required - Protected endpoints: `store`, `destroy` - Requires JWT authentication

Endpoints

1. Find Nearby Churches

GET `/api/churches/nearby`

Find Catholic churches within a specified radius of a location.

Parameters: - `lat` (required, float): Latitude (-90 to 90) - `lng` (required, float): Longitude (-180 to 180) - `radius` (optional, float): Search radius in kilometers (default: 10, max: 100) - `limit` (optional, integer): Maximum results (default: 50, max: 100)

Response: ```json { "success": true, "message": "Nearby churches retrieved successfully", "data": [ { "id": 1, "name": "St. Patrick's Cathedral", "address": "5th Ave, New York, NY 10022, USA", "phone_number": "(212) 753-2261", "website": "https://www.saintpatrickscathedral.org", "latitude": 40.7597, "longitude": -73.9798, "mass_times": "Mon-Fri: 7:00 AM, 12:00 PM, 5:30 PM | Sat: 4:00 PM | Sun: 8:00 AM, 10:00 AM, 12:00 PM, 5:30 PM", "notes": "Famous Neo-Gothic Catholic cathedral in Midtown Manhattan", "is_user_added": false, "created_at": "2024-03-22T10:30:00.000000Z", "distance": 2.5, "formatted_distance": "2.5km", "short_address": "5th Ave, New York, NY" } ] } ```

2. Search Churches

GET `/api/churches/search`

Search churches by name or address.

Parameters: - `q` (required, string): Search query (minimum 2 characters) - `limit` (optional, integer): Maximum results (default: 20, max: 20)

Response: Same format as nearby endpoint without distance data.

3. Get Church Details

GET `/api/churches/{id}`

Get detailed information about a specific church.

Response: Same format as nearby endpoint for a single church.

4. Create Church

POST `/api/churches`

Add a new church (requires authentication).

Request Body: ```json { "name": "St. Mary's Catholic Church", "address": "123 Main St, City, State 12345", "phone_number": "(555) 123-4567", "website": "https://stmarys.com", "latitude": 40.7128, "longitude": -74.0060, "mass_times": "Sat 5:00 PM, Sun 8:00 AM, 10:00 AM", "notes": "Additional information about the church" } ```

Required Fields: - `name` (string, max 255 chars) - `address` (string, max 500 chars) - `latitude` (float, -90 to 90) - `longitude` (float, -180 to 180)

Optional Fields: - `phone_number` (string, max 20 chars) - `website` (URL, max 255 chars) - `mass_times` (string, max 1000 chars) - `notes` (string, max 1000 chars)

Response: ```json { "success": true, "message": "Church created successfully", "data": { // Church object with server-generated ID } } ```

5. Delete Church

DELETE `/api/churches/{id}`

Delete a user-added church (requires authentication and ownership).

Response: ```json { "success": true, "message": "Church deleted successfully" } ```

6. Get Statistics

GET `/api/churches/stats`

Get church statistics (public endpoint).

Response: ```json { "success": true, "message": "Statistics retrieved successfully", "data": { "total_churches": 1500, "user_added_churches": 250, "pending_approval": 15 } } ```

Data Model

Church Object

```typescript interface Church { id: number; name: string; address: string; phone_number?: string; website?: string; latitude: number; longitude: number; mass_times?: string; notes?: string; is_user_added: boolean; created_at: string; distance?: number; // Only in nearby searches formatted_distance?: string; // Computed short_address?: string; // Computed } ```

Error Responses

All endpoints return consistent error responses:

```json { "success": false, "message": "Error description", "data": [] } ```

Common HTTP Status Codes: - `200` - Success - `201` - Created (for POST requests) - `400` - Bad Request (validation errors) - `403` - Forbidden (permission denied) - `404` - Not Found - `500` - Internal Server Error

Special Features

Geospatial Search

- Uses Haversine formula for accurate distance calculations - Results automatically sorted by distance (closest first) - Supports radius up to 100km

Auto-Approval

Churches are automatically approved if they: - Are not user-added (system churches) - Have complete information (phone + website) - Have Catholic-identifying names (contain "Catholic", "St.", "Saint") - Include Mass times information

Catholic Detection

The API identifies Catholic churches through: - Name patterns (Catholic, St., Saint, etc.) - Mass times presence - Notes containing "Catholic"

Rate Limiting

- Public endpoints: 100 requests per minute per IP - Authenticated endpoints: 1000 requests per minute per user

CORS Configuration

The API supports cross-origin requests from the Catholic Daily app.

Usage Examples

Find churches near Manhattan

```bash curl "https://api.elbiblio.com/api/churches/nearby?lat=40.7589&lng=-73.9851&radius=5" ```

Search for "St. Mary"

```bash curl "https://api.elbiblio.com/api/churches/search?q=St.%20Mary" ```

Add a new church (with auth token)

```bash curl -X POST "https://api.elbiblio.com/api/churches" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "St. Mary''s Church", "address": "123 Main St", "latitude": 40.7128, "longitude": -74.0060 }' ```

Database Schema

```sql CREATE TABLE churches ( id BIGINT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(255) NOT NULL, address TEXT NOT NULL, phone_number VARCHAR(20) NULL, website VARCHAR(255) NULL, latitude DECIMAL(10,8) NOT NULL, longitude DECIMAL(11,8) NOT NULL, mass_times TEXT NULL, notes TEXT NULL, is_user_added BOOLEAN DEFAULT FALSE, created_by BIGINT NULL REFERENCES users(id), approved_at TIMESTAMP NULL, approved_by BIGINT NULL REFERENCES users(id), created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP );

INDEXES: - INDEX idx_coordinates (latitude, longitude) - INDEX idx_user_added (is_user_added) - INDEX idx_approved (approved_at) - INDEX idx_name (name) - FULLTEXT idx_search (name, address) ```

Testing

Sample Test Data

The API includes 10 sample Catholic churches in major US cities: - New York: St. Patrick's Cathedral, St. Michael's Church - Chicago: Holy Name Cathedral, St. Mary's Church - Los Angeles: Cathedral of Our Lady of the Angels - Washington DC: Basilica of the National Shrine - San Francisco: St. Mary's Cathedral - San Jose: Cathedral Basilica of St. Joseph - Phoenix: St. Peter's Church - Tucson: St. Paul the Apostle Church

Test Coordinates

- Manhattan: `lat=40.7589, lng=-73.9851` - Chicago Loop: `lat=41.8781, lng=-87.6298` - Los Angeles Downtown: `lat=34.0522, lng=-118.2437`

Integration Notes

Flutter App Integration

The Catholic Daily Flutter app integrates with these endpoints to: - Display nearby churches when user grants location permission - Allow users to add missing churches manually - Cache results locally for offline access - Provide one-tap calling and website access

Error Handling

The Flutter app gracefully handles: - Network failures (falls back to cached data) - Location permission denial (shows manual entry option) - API errors (displays user-friendly messages) - Invalid coordinates (validates before API calls)