Repository navigation
Add iNaturalist Integration #252
Description
Description
Integrate iNaturalist as an external data source for community observations, images, and species occurrence data.
Background
iNaturalist is a citizen science platform with:
- 90+ million observations of plants and animals
- High-quality community-verified images
- Location and habitat data
- Research-grade observations verified by experts
- Free REST API access
Benefits
- Rich image library: Multiple photos per species showing variation
- Habitat context: Photos in natural settings
- Geographic data: Where species are actually observed
- Community engagement: Real-world breeding observations
API Overview
Base URL: https://api.inaturalist.org/v1/
Key Endpoints:
GET /taxa/autocomplete?q={scientific_name}- Find taxon by nameGET /taxa/{id}- Get taxon detailsGET /observations?taxon_id={id}- Get observations with photos
Rate Limiting: 60 requests/minute (conservative: use 100ms delay)
Implementation Plan
1. Create Integration Client
// src/integrations/inaturalist.ts
export interface iNaturalistResult {
found: boolean;
taxon_url?: string;
images?: Array<{
url: string;
photographer?: string;
license?: string;
observation_url?: string;
}>;
observations_count?: number;
}
export async function getExternalData(
genus: string,
species: string
): Promise<iNaturalistResult>;2. Create Sync Script
scripts/sync-inaturalist-all-species.ts3. Integration Points
- Add to master orchestrator (`sync-all-species-full-database.ts`)
- Store URLs in `species_external_references` table
- Download images to R2 with photographer attribution
- Track with source='inaturalist'
Tasks
- Create `src/integrations/inaturalist.ts` client
- Implement taxon search and photo retrieval
- Create sync script with `--download-images` support
- Add to master orchestrator
- Test with various species types
- Handle Creative Commons licenses properly
- Update documentation
Acceptance Criteria
- iNaturalist API client successfully finds taxa
- Images downloaded with photographer attribution
- License information stored (CC-BY, CC-BY-NC, etc.)
- Rate limiting respects API guidelines
- Sync integrates with existing workflow
- Documentation updated
Notes
- License compliance: Most images are CC-BY or CC-BY-NC
- Attribution required: Store photographer name and observation URL
- Photo quality: Filter for research-grade observations
Priority
Medium - Great for image diversity and community data.
Related to #240 (External Data Sources Integration)
Activity