API Documentation
Ephemeros offers API access to its growing record of repeat photography for research purposes: the photo series themselves, capture metadata (position, heading, tilt), weather data recorded at capture time, AI-generated content tags, and full-resolution dataset downloads per spot. Only approved, publicly visible content is ever exported.
Access requires an API key, which we issue to research projects on request — email us at hello@ephemeros.app with a short description of your project to request one. API access is governed by the Researcher Data Access Agreement (the researcher terms); the photos and metadata themselves are openly licensed CC BY 4.0.
Authentication
Send your key with every request in the
X-Api-Key header. Keys are
rate-limited per minute and may carry daily/monthly request quotas, an expiry date, and access
restrictions (geographic areas, date ranges, data categories) agreed for your project. Call
GET /api/export/v1/me at any time
to see your key's exact scope, permissions, quota usage and expiry.
Formats and pagination
Responses are JSON by default. The list endpoints also accept
format=csv and are paginated at
500 rows per page via the page
parameter.
Endpoints
| Endpoint | Returns | Parameters |
|---|---|---|
| GET /api/export/v1/spots | Photo spots with location, type and photo counts | viewport (sw_lat, sw_lng, ne_lat, ne_lng), spot_type_id / spot_type (slug), list_uuid, q, min_photo_count, created_from/created_to, format, page |
| GET /api/export/v1/photos | Photos with capture metadata, weather and AI tags | spot_uuid, viewport, captured_from/captured_to, spot_type_id / spot_type, ai_tag, ai_text, aligned, min_alignment_score, device_model, updated_after, variant=original|aligned|both, format, page |
| GET /api/export/v1/spots/{uuid}/timelapse | The spot's timelapse video URL and generation time | — |
| GET /api/export/v1/spot-types | Active spot types (id, slug, name) for use in filters | — |
| GET /api/export/v1/lists | Public curated lists of spots, for corpus discovery | page |
| GET /api/export/v1/me | Your key's scope, permissions, quotas and usage, and expiry | — |
| GET /api/export/v1/dataset | Queues a full-resolution ZIP of one spot's photo series; returns the export UUID | spot_uuid (required), variant |
| GET /api/export/v1/dataset/{uuid} | Status of a queued export, with a download URL once ready | — |
Example
curl -H "X-Api-Key: eph_…" "https://ephemeros.app/api/export/v1/photos?captured_from=2026-01-01&format=csv"
Questions, an API key request, higher rate limits, or data needs not covered here? Email hello@ephemeros.app or get in touch via the contact form.
