API Documentation

Complete guide to integrating Ancestor's genealogy analysis API into your applications

Getting Started

1. Get API Key

Sign up for a free API key to start analyzing ancestry data

Get Free Key

2. Make First Call

Use our simple REST API to evaluate ancestry data

3. Monitor Usage

Track your API usage and performance in the dashboard

View Dashboard
Base URL
https://ancestor.cloud/api/v1

Authentication

API Key Authentication
All API requests require authentication using your API key in the Authorization header

Header Format:

Authorization: Bearer your_api_key_here

Keep your API key secure

Never expose your API key in client-side code or public repositories

API Endpoints

POST/evaluate
Core Endpoint
Analyze ancestry data and return trust scores with detailed analysis

Request Body:

{ "data": { "individual": "string", "birth_year": number, "location": "string", "sources": ["string"] }, "analysis_type": "basic" | "comprehensive" }

Response:

{ "trust_score": 85, "analysis": "High confidence based on multiple sources...", "sources_analyzed": 3, "confidence_factors": [ "Multiple corroborating records", "Consistent dates and locations" ], "recommendations": [ "Consider additional census records" ] }
GET/usage
Monitoring
Get your current API usage statistics and remaining quota

Response:

{ "current_usage": 245, "monthly_limit": 1000, "remaining": 755, "reset_date": "2024-02-01T00:00:00Z", "plan": "free" }

Code Examples

Quick Start Examples
Get started quickly with these code examples in your preferred language
import requests

# Initialize the client
api_key = "your_api_key_here"
base_url = "https://ancestor.cloud/api/v1"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

# Evaluate ancestry data
def evaluate_ancestry(data):
    response = requests.post(
        f"{base_url}/evaluate",
        headers=headers,
        json={
            "data": data,
            "analysis_type": "comprehensive"
        }
    )
    return response.json()

# Example usage
result = evaluate_ancestry({
    "individual": "John Smith",
    "birth_year": 1850,
    "location": "Boston, MA",
    "sources": ["census_1870", "birth_record"]
})

print(f"Trust Score: {result['trust_score']}")
print(f"Analysis: {result['analysis']}")

Error Handling

HTTP Status Codes
200Success
Request completed successfully
400Bad Request
Invalid request parameters
401Unauthorized
Invalid or missing API key
429Rate Limited
Too many requests
Error Response Format
{ "error": { "code": "INVALID_REQUEST", "message": "Missing required field: individual", "details": { "field": "data.individual", "expected": "string" } } }

Rate Limits

Free Plan
Monthly Limit:1,000 requests
Rate Limit:10 req/min
Burst Limit:20 requests
Pro Plan
Monthly Limit:Unlimited
Rate Limit:100 req/min
Burst Limit:200 requests

Need Help?

Our support team is here to help you integrate successfully