Developer API

Convert Programmatically

Integrate GEDCOM ↔ JSON conversion directly into your applications with our simple REST API.

50/hr

Free tier limit

500/hr

With API key

<100ms

Avg response time

Base URL

https://ged2json.com/api/v1

Endpoints

POST`/convert`

Convert between GEDCOM and JSON formats. Returns the converted data directly in the response.

Request Body (JSON)

Field	Type	Required	Description
`direction`	string	Yes	`"ged-to-json"` or `"json-to-ged"`
`content`	string	Yes	The GEDCOM or JSON content to convert

Headers

Header	Required	Description
`Content-Type`	Yes	`application/json`
`X-API-Key`	No	Your API key for higher rate limits (500/hr vs 50/hr)

Success Response

{
  "success": true,
  "data": {
    "format": "json",
    "data": {
      "header": { ... },
      "individuals": [ ... ],
      "families": [ ... ],
      "sources": [ ... ]
    },
    "stats": {
      "individuals": 42,
      "families": 15,
      "sources": 8
    }
  }
}

GET`/health`

Check API status and get version information.

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "endpoints": {
    "convert": "/api/v1/convert",
    "health": "/api/v1/health"
  },
  "limits": {
    "anonymous": "50 requests/hour",
    "withApiKey": "500 requests/hour",
    "maxFileSize": "50MB"
  }
}

Code Examples

curl -X POST https://ged2json.com/api/v1/convert \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "ged-to-json",
    "content": "0 HEAD\n1 SOUR MyApp\n0 @I1@ INDI\n1 NAME John /Smith/\n0 TRLR"
  }'

Rate Limiting

Rate limit information is included in response headers:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 49
X-RateLimit-Reset: 1705312200000

Anonymous

50 requests per hour

Based on IP address

With API Key

500 requests per hour

Error Codes

Code	HTTP Status	Description
`INVALID_REQUEST`	400	Missing required fields
`INVALID_GEDCOM`	400	Malformed GEDCOM content
`INVALID_JSON`	400	Malformed JSON content
`INVALID_JSON_STRUCTURE`	400	JSON missing required arrays
`CONTENT_TOO_LARGE`	400	Content exceeds 50MB limit
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`CONVERSION_ERROR`	500	Internal conversion failure

Error Response Format

{
  "success": false,
  "error": {
    "message": "Invalid GEDCOM: Missing required HEAD record",
    "code": "INVALID_GEDCOM"
  }
}

File Upload (Alternative)

You can also upload files using multipart/form-data:

curl -X POST https://ged2json.com/api/v1/convert \
  -H "X-API-Key: your-api-key" \
  -F "file=@family-tree.ged" \
  -F "direction=ged-to-json"