API Documentation

Complete guide to using the VoterHub API for accessing and managing voter registration data.

API Overview

Base URL

https://your-domain.com/api

Content Type

application/json

Available Endpoints

GET
/voter-registration - Retrieve voter registration data
POST
/voter-registration - Create new registration record
POST
/voter-registration/import - Bulk import CSV data

Authentication

Security Notice: POST operations require authentication. GET requests are public.

Method 1: API Key Header

X-API-Key: your-api-password

Method 2: Bearer Token

Authorization: Bearer your-api-password

Getting API Access

Contact your system administrator to obtain the API password. The password is required for all data modification operations.

Rate Limits

GET Requests

120

requests per minute

POST Requests

requests per minute

Import Operations

requests per hour

Note: Rate limits are applied per IP address. Exceeding limits returns HTTP 429.

API Endpoints

GET

/api/voter-registration

Description

Retrieve voter registration data with optional filtering and sorting.

Query Parameters

Parameter	Type	Description	Default
`sortBy`	string	Column to sort by	state
`sortOrder`	string	Sort direction (asc/desc)	asc
`filter`	string	Search term for filtering	-

Example Request

curl -X GET "https://your-domain.com/api/voter-registration?sortBy=state&sortOrder=asc&filter=california" \
  -H "Content-Type: application/json"

Example Response

{
  "data": [
    {
      "id": 1,
      "state": "California",
      "registration_deadline_in_person": "2024-10-21",
      "registration_deadline_by_mail": "2024-10-07",
      "registration_deadline_online": "2024-10-07",
      "election_day_registration": null,
      "online_registration_link": "https://registertovote.ca.gov/",
      "description": "California voter registration information"
    }
  ],
  "success": true,
  "meta": {
    "count": 1,
    "sortBy": "state",
    "sortOrder": "asc",
    "filter": "california"
  }
}

Error Responses

HTTP Status Codes

400

Bad Request

Invalid request data or missing required fields

401

Unauthorized

Missing or invalid API password

429

Rate Limited

Too many requests, rate limit exceeded

500

Server Error

Internal server or database error

Error Response Format

{
  "error": "Authentication required",
  "success": false,
  "details": "Additional error details (development only)"
}

Code Examples

Fetch Voter Registration Data

// Fetch voter registration data
async function getVoterData(filter = '', sortBy = 'state') {
  try {
    const params = new URLSearchParams({
      sortBy,
      sortOrder: 'asc',
      filter
    });
    
    const response = await fetch(`/api/voter-registration?${params}`);
    const data = await response.json();
    
    if (data.success) {
      console.log('Found', data.meta.count, 'records');
      return data.data;
    } else {
      throw new Error(data.error);
    }
  } catch (error) {
    console.error('Error fetching data:', error);
  }
}

// Usage
getVoterData('california', 'state').then(data => {
  console.log(data);
});

Create New Record

// Create a new voter registration record
async function createRecord(recordData, apiPassword) {
  try {
    const response = await fetch('/api/voter-registration', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': apiPassword
      },
      body: JSON.stringify(recordData)
    });
    
    const result = await response.json();
    
    if (response.status === 401) {
      throw new Error('Invalid API password');
    } else if (response.status === 429) {
      throw new Error('Rate limit exceeded');
    } else if (result.success) {
      console.log('Record created:', result.data);
      return result.data;
    } else {
      throw new Error(result.error);
    }
  } catch (error) {
    console.error('Error creating record:', error);
  }
}

// Usage
const newRecord = {
  state: 'Nevada',
  registration_deadline_in_person: '2024-10-29',
  registration_deadline_by_mail: '2024-10-15',
  registration_deadline_online: '2024-10-29',
  election_day_registration: 'Available',
  online_registration_link: 'https://www.nvsos.gov/',
  description: 'Nevada allows same-day registration'
};

createRecord(newRecord, 'your-api-password');

Best Practices

Security

• Store API passwords securely (environment variables)
• Use HTTPS for all API requests
• Implement proper error handling
• Don't log API passwords in application logs

Performance

• Respect rate limits to avoid 429 errors
• Use filtering to reduce response sizes
• Implement client-side caching when appropriate
• Batch operations when possible

Data Handling

• Validate data before sending to API
• Handle partial failures in bulk operations
• Use proper date formats (YYYY-MM-DD)
• Sanitize user input before API calls

Error Handling

• Check HTTP status codes before processing
• Implement retry logic for transient errors
• Provide meaningful error messages to users
• Log errors for debugging purposes