01
Track astronomical targets
Your observing app can calculate an object's changing altitude and azimuth, then sample modeled skyglow along its apparent path to identify darker portions of the trajectory.
Light Pollution API Reference
DarkSkySites.comDarkSkySites / Developer platform
We simulate the night sky so you can focus on building!
Use our astronomer-calibrated digital atmosphere to query light pollution data and deep-sky object tracking from anywhere on Earth.
DarkSkySites provides global, physics-based estimates of night-sky brightness, combining satellite observations, atmospheric scattering models and empirical calibration to predict how artificial light affects the sky at any location on Earth.
Access zenith SQM, estimated Bortle classes and historical datasets, model sky brightness at any altitude and azimuth, or plan fixed-target observing timelines with SkyTrack to reveal light domes and identify useful observing windows.
Built for astronomy software, astrophotography planners and geospatial applications. Responses include source, data-quality and usage information; SkyTrack adds target geometry, modeled backgrounds and conditional imaging-impact estimates.
DarkSkySites does your heavy lifting. All you need to do is build!
01 / Application context
The Free API describes the modeled sky directly overhead and supports location comparison. Pro adds directional SQM, monthly history and SkyTrack, a fixed-target timeline endpoint for visibility, modeled background and optional conditional imaging-impact windows.
01
Your observing app can calculate an object's changing altitude and azimuth, then sample modeled skyglow along its apparent path to identify darker portions of the trajectory.
02
Compare artificial sky brightness in the Milky Way direction as it moves during a session, especially near bright horizons or moderately light-polluted locations.
03
Sample low-altitude compass directions to characterize light domes, identify relatively dark sectors and compare them with nearby city directions.
04
Query target-relevant directions at multiple sites to find potentially better locations for a specific observation, rather than comparing zenith SQM alone.
05
SkyTrack aligns up to eight fixed targets on one timeline, showing visible-dark duration, peak altitude, modeled background and darkest or highest-efficiency 30, 60 and 120-minute windows when requested.
Applications include astrophotography tools, observing planners, target tracking, light-pollution maps, location intelligence and environmental research.
01 / One explicit request
Try a live zenith query without an account or API key. Demo requests are rate-limited. The public demo does not use your account's quota; authenticated API requests require an API key.
Response preview
After a successful request, inspect modeled SQM, derived Bortle, selected dataset, quality status and the unmodified response body here.
02 / Directional model
A zenith-only value can hide a bright urban horizon. The simulator shows how modeled brightness varies by altitude and direction at the observer location.
Enable JavaScript and use a WebGPU-capable browser to explore the interactive sky simulator.
03 / Native directional response
Enable JavaScript to search places, submit queries and render the sky canvas.
Awaiting explicit query
A successful native response supplies the canvas reference and directional marker. Existing successful results stay visible if later inputs or requests change.
03 / Access at a glance
| Capability | Free | Pro |
|---|---|---|
| Zenith SQM and Bortle estimate | Included | Included |
| Directional sky brightness | Not included | By altitude and azimuth |
| Monthly Zenith history | Not included | Exact calendar-month entries |
| Fixed-target timelines | Not included | Full DSO tracks via SkyTrack |
| Standard limits | 30,000 / month, 10 / second, 3 active keys | See Pro quotas |
Free / API documentation
01 / Authentication and first request
Request a zenith estimate for a latitude and longitude. The response identifies the selected dataset and includes fallback and quality information. Authenticate with the x-api-key request header. Do not embed a key in public browser code, a URL, or a shared source repository.
curl --get 'https://darkskysites.com/api/sqm' \
--data-urlencode 'lat=35.2401' \
--data-urlencode 'lng=14.4378' \
--header 'x-api-key: YOUR_API_KEY'// Server-side JavaScript
const response = await fetch('https://darkskysites.com/api/sqm?lat=35.2401&lng=14.4378', {
headers: { 'x-api-key': process.env.DARKSKYSITES_API_KEY }
});
const data = await response.json();
if (!response.ok) throw new Error(data.error || 'SQM request failed');
if (data.dataset.fallbackUsed) {
console.warn('Using older data:', data.dataset.id, data.dataset.fallbackReason);
}
console.log('Quality:', data.quality);
console.log(data);import os
import requests
response = requests.get(
'https://darkskysites.com/api/sqm',
params={'lat': 35.2401, 'lng': 14.4378},
headers={'x-api-key': os.environ['DARKSKYSITES_API_KEY']}
)
response.raise_for_status()
data = response.json()
if data["dataset"]["fallbackUsed"]:
print("Using older data:", data["dataset"]["id"], data["dataset"]["fallbackReason"])
print("Quality:", data["quality"])
print(data)Example coordinates are decimal degrees. A successful GET /api/sqm request uses one zenith request from the project allowance.
02 / Interpreting Zenith
SQM is magnitudes per square arcsecond. The value describes modeled brightness overhead; larger values represent a darker sky. Bortle class and description are derived from that SQM value. They are not direct visual observations, SQM meter measurements, weather conditions, or a guarantee of observing quality.
03 / Endpoint and parameters
/api/sqmFree accessReturns the latest usable zenith SQM and its SQM-derived Bortle class, with dataset and quality information.
GET /api/sqm?lat=35.799&lng=14.588Required query fields are lat and lng. Optional date accepts YYYY-MM or MM_YYYY where the project has date-selection access; standard Free keys may receive PRO_REQUIRED for an explicit date.
| Field | Description |
|---|---|
| lat | Required. Decimal latitude from -90 through 90. |
| lng | Required. Decimal longitude from -180 through 180. |
| date | Optional where the project has date-selection access. YYYY-MM or MM_YYYY. Standard Free keys may receive PRO_REQUIRED for an explicit date. An earlier usable dataset may be returned. |
When you request a month using /api/sqm, it may return an earlier month if the requested data is missing or unusable. Pro history keeps the months you request and clearly marks any missing data.
04 / Response
This is the published sample response. Values depend on the requested location and selected source dataset.
{
"latitude": 35.2401,
"longitude": 14.4378,
"sqm": 21.77,
"bortleClass": 2,
"bortleDescription": "Typical truly dark site",
"dataset": {
"id": "08_2026",
"year": 2026,
"month": 8,
"requestedDate": null,
"fallbackUsed": false,
"fallbackFrom": null,
"fallbackReason": null,
"datasetsChecked": 1
},
"quality": {
"status": "screened",
"method": "seasonal_temporal_v1",
"coverageVerified": false,
"flags": []
},
"attribution": "darkskysites.com"
}| Field | Description |
|---|---|
| latitude / longitude | Observer coordinates returned as decimal degrees. |
| sqm | Modeled zenith brightness in mag/arcsec². Higher values mean a darker modeled sky. This is not a live meter reading. |
| bortleClass / bortleDescription | A classification derived from returned SQM, not an observed visual class. |
| dataset.id / year / month | Selected source dataset identifier, year and month, requestedDate, fallbackUsed, fallbackFrom, fallbackReason and datasetsChecked. |
| quality | status, method, coverageVerified and screening flags. coverageVerified is always false. |
| attribution | Required source attribution string, darkskysites.com. |
05 / DATASET SELECTION AND QUALITY
DarkSkySites selects the latest usable monthly dataset and includes its source and quality information in the response.
Without date, the API checks enabled datasets from newest to oldest and returns the first usable result.
If the requested month is unavailable, the API searches earlier datasets and identifies the month returned. Read dataset.id for that month.
| Field | Meaning |
|---|---|
| dataset.id | Month returned, formatted MM_YYYY. |
| dataset.year / dataset.month | Year and month returned. |
| dataset.requestedDate | Requested date, or null if omitted. |
| dataset.fallbackUsed | True when returned ID differs from the requested month normalized to MM_YYYY, or the latest candidate when date is omitted. |
| dataset.fallbackFrom | Comparison month when different from the returned month; otherwise null. |
| dataset.fallbackReason | First reason the comparison month was skipped, or null. |
| dataset.datasetsChecked | Distinct datasets evaluated, including comparison checks. |
Screened data has passed quality checks, but satellite coverage cannot be independently verified. The response records this as quality.coverageVerified=false.
unverified_zero may indicate genuine darkness or unavailable observations. Do not present it as confirmed pristine sky.
JavaScript Ā· parsed response data
const monthUsed = data.dataset.id;
if (data.dataset.fallbackUsed) {
console.info("Different month returned:", monthUsed, data.dataset.fallbackReason);
}
if (data.quality.status === "unverified_zero") {
console.warn("Darkness is uncertain. Show a data-quality notice.");
}Monthly sky-brightness estimates use LUMIX calibration and local LLFC corrections. They are not live SQM meter readings, real-time weather or cloud conditions, or direct observations at a specific place and time.
| Field | Meaning |
|---|---|
| quality.status | screened, unverified_zero, or unavailable on no-result errors. |
| quality.method | Rule version: seasonal_temporal_v1. |
| quality.coverageVerified | Always false; source coverage cannot be verified. |
| quality.flags | Screening reasons, including zero_brightness_unverified when applicable. |
datasetsChecked without changing fallbackUsed.unverified_zero.05 / Limits and errors
30,000
Zenith requests per month
10
requests per second
3
active keys per project
These are standard Free project limits. Existing custom project arrangements retain their configured limits. Free error responses do not use the structured Pro error envelope.
| Field | Description |
|---|---|
| 400 | Invalid coordinates or date format. |
| 401 | Missing or invalid API key. |
| 403 | Project access is suspended, revoked or does not include the requested access. |
| 404 | No usable dataset was found within the bounded candidate search. |
| 429 | Request rate or monthly allowance reached. Observe any retry guidance. |
| 503 | Data, storage or service capacity is temporarily unavailable. Retry later. |
06 / Attribution
Free API use requires visible attribution wherever data is displayed. Place āDarkSkySites.comā adjacent to the data and link it to https://darkskysites.com wherever hyperlinks are supported. See the API Terms of Use.
Free / access
Free self-service access requires an account and project activation in the developer dashboard. No credit card is required.
Pro / API documentation
APEX uses annual datasets. Monthly directional queries are not currently supported.
01 / Single-direction request
Light pollution varies across the sky. A nearby city might brighten one horizon while the opposite direction remains much darker.
Zenith SQM describes modeled sky brightness directly overhead. APEX estimates brightness in any direction using altitude and azimuth.
Your application supplies the direction, for example along a target's apparent path, to identify darker observing directions and locations.
APEX does not predict weather, seeing or transparency.
/api/sqm/directionalPro accessComputes modeled SQM and its derived Bortle class at the requested altitude and azimuth; this is not necessarily the zenith.
alt is degrees above the horizon; az is degrees clockwise from north. The response identifies the annual source dataset and any fallback.
| Field | Description |
|---|---|
| lat | Required. Observer latitude, -90 through 90 degrees. |
| lng | Required. Observer longitude, -180 through 180 degrees. |
| alt | Required. Angular elevation above the horizon, 0 through 90 degrees. 0 is the horizon; 90 is zenith. |
| az | Required. Compass bearing clockwise from north, 0 through 360 degrees. 0 is north, 90 east, 180 south, 270 west. Values are range-validated and not silently normalized. |
| x-api-key | Required header for public API-key endpoints. Never send a key in a URL. |
APEX uses an annual dataset and may fall back to an earlier year if necessary. The response identifies the dataset returned.
Directional Bortle estimates are derived from modeled SQM, not from direct visual observations. They describe the requested direction, not an observed overall Bortle sky classification.
curl 'https://darkskysites.com/api/sqm/directional?lat=40.8366&lng=-105.2052&alt=25&az=90' \
--header 'x-api-key: YOUR_API_KEY'// Server-side JavaScript. Never expose your API key in a public app.
const response = await fetch('https://darkskysites.com/api/sqm/directional?lat=40.8366&lng=-105.2052&alt=25&az=90', {
method: 'GET',
headers: {
'x-api-key': process.env.DARKSKYSITES_API_KEY
}
});
const data = await response.json();
if (!response.ok) throw new Error(data.error || 'API request failed');
console.log(data);import os
import requests
response = requests.get(
'https://darkskysites.com/api/sqm/directional?lat=40.8366&lng=-105.2052&alt=25&az=90',
headers={'x-api-key': os.environ['DARKSKYSITES_API_KEY']},
timeout=30,
)
response.raise_for_status()
data = response.json()
print(data)02 / Multiple directions
Calculate sky brightness for multiple directions with a single API request. You can either:
Choose one method per request. The maximum number of directions depends on your account's API limits.
/api/sqm/directionsPro accessSubmit one direction, three directions, or a larger directions array. An optional generated horizon profile is another request form, not a requirement.
Each direction uses alt and az. Alternatively provide profile: { "type": "horizon", "azimuthStep": 30, "altitudes": [15, 30] }. Arrays are subject to configured request bounds.
| Field | Description |
|---|---|
| latitude / longitude | Required observer coordinates. Latitude -90..90; longitude -180..180. |
| directions[] | An array of one or more { alt, az } objects. alt is 0..90 degrees; az is 0..360 degrees. Use this form OR profile. |
| profile.type | Required literal "horizon" when using a generated profile. |
| profile.azimuthStep | Integer from 1 through 360 that divides 360 exactly. |
| profile.altitudes[] | One or more unique altitude bands in the range 0..90 degrees. |
| x-api-key / Idempotency-Key | x-api-key is required. Idempotency-Key is optional and accepts 1 to 128 printable ASCII characters. |
A series of positions can follow a target's calculated transit or compare the Milky Way's direction at multiple observing times. A horizon profile can expose a bright urban light dome relative to darker compass sectors.
curl 'https://darkskysites.com/api/sqm/directions' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"latitude": 40.8366,
"longitude": -105.2052,
"directions": [
{
"alt": 15,
"az": 0
},
{
"alt": 30,
"az": 90
},
{
"alt": 45,
"az": 180
}
]
}'// Server-side JavaScript. Never expose your API key in a public app.
const response = await fetch('https://darkskysites.com/api/sqm/directions', {
method: 'POST',
headers: {
'x-api-key': process.env.DARKSKYSITES_API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"latitude": 40.8366,
"longitude": -105.2052,
"directions": [
{
"alt": 15,
"az": 0
},
{
"alt": 30,
"az": 90
},
{
"alt": 45,
"az": 180
}
]
})
});
const data = await response.json();
if (!response.ok) throw new Error(data.error || 'API request failed');
console.log(data);import os
import requests
response = requests.post(
'https://darkskysites.com/api/sqm/directions',
headers={'x-api-key': os.environ['DARKSKYSITES_API_KEY']},
json={
"latitude": 40.8366,
"longitude": -105.2052,
"directions": [
{
"alt": 15,
"az": 0
},
{
"alt": 30,
"az": 90
},
{
"alt": 45,
"az": 180
}
]
},
timeout=30,
)
response.raise_for_status()
data = response.json()
print(data)This example returns 48 positions: 24 compass bearings at each of two altitude bands. It uses the same batch endpoint, not a separate horizon endpoint.
curl 'https://darkskysites.com/api/sqm/directions' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"latitude": 40.8366,
"longitude": -105.2052,
"profile": {
"type": "horizon",
"azimuthStep": 15,
"altitudes": [
15,
30
]
}
}'// Server-side JavaScript. Never expose your API key in a public app.
const response = await fetch('https://darkskysites.com/api/sqm/directions', {
method: 'POST',
headers: {
'x-api-key': process.env.DARKSKYSITES_API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"latitude": 40.8366,
"longitude": -105.2052,
"profile": {
"type": "horizon",
"azimuthStep": 15,
"altitudes": [
15,
30
]
}
})
});
const data = await response.json();
if (!response.ok) throw new Error(data.error || 'API request failed');
console.log(data);import os
import requests
response = requests.post(
'https://darkskysites.com/api/sqm/directions',
headers={'x-api-key': os.environ['DARKSKYSITES_API_KEY']},
json={
"latitude": 40.8366,
"longitude": -105.2052,
"profile": {
"type": "horizon",
"azimuthStep": 15,
"altitudes": [
15,
30
]
}
},
timeout=30,
)
response.raise_for_status()
data = response.json()
print(data)03 / Monthly history
Historical zenith SQM can help show whether a location has become brighter or darker and how modeled light pollution has changed over time.
/api/sqm/historyPro accessReturns one exact calendar-month entry for every month in the requested range. Months without usable data remain explicit unavailable entries; the response does not substitute another month.
Optional from and to use YYYY-MM. Omit them for complete available monthly history. Historical baseSqm is the original model; sqm applies current LLFC corrections.
| Field | Description |
|---|---|
| lat | Required. Latitude from -90 through 90 degrees. |
| lng | Required. Longitude from -180 through 180 degrees. |
| from | Optional start month, YYYY-MM. If both bounds are given, from must not be later than to. |
| to | Optional end month, YYYY-MM. Future months are not supported. |
| x-api-key / Idempotency-Key | x-api-key is required. Idempotency-Key is optional and accepts 1 to 128 printable ASCII characters. |
Pro history returns exact calendar-month entries for the requested date range, with missing periods explicitly disclosed. Historical data describes the available modeled record, not live observation. A successful history request uses one zenith request, regardless of the number of months returned.
curl 'https://darkskysites.com/api/sqm/history?lat=40.8366&lng=-105.2052&from=2024-01&to=2024-03' \
--header 'x-api-key: YOUR_API_KEY'// Server-side JavaScript. Never expose your API key in a public app.
const response = await fetch('https://darkskysites.com/api/sqm/history?lat=40.8366&lng=-105.2052&from=2024-01&to=2024-03', {
method: 'GET',
headers: {
'x-api-key': process.env.DARKSKYSITES_API_KEY
}
});
const data = await response.json();
if (!response.ok) throw new Error(data.error || 'API request failed');
console.log(data);import os
import requests
response = requests.get(
'https://darkskysites.com/api/sqm/history?lat=40.8366&lng=-105.2052&from=2024-01&to=2024-03',
headers={'x-api-key': os.environ['DARKSKYSITES_API_KEY']},
timeout=30,
)
response.raise_for_status()
data = response.json()
print(data)04 / Response contracts
APEX responses include directional results and the zenith reference used by the model. History responses include every requested month, with missing data marked unavailable. The SkyTrack response adds a shared time axis, fixed-target samples, modeled environment and optional per-target imaging-impact summaries.
These complete JSON examples use synthetic values from verified test fixtures, not live sky readings. The single-direction example shows annual source fallback. The batch example uses the standard trial's one-direction-per-unit policy. null usage balances mean the balance and reset time are not supplied in that example.
| Field | Description |
|---|---|
| apiVersion | The response contract identifier, pro-v1. |
| requestId | Identifier for this request or replayed receipt. |
| latitude / longitude | Observer coordinates in decimal degrees. |
| unit | Modeled brightness unit, mag/arcsec². |
| attribution | Required attribution string, darkskysites.com. |
| usage | Resource charged, units charged, remaining allowance when known, and resetAt when known. |
| Field | Description |
|---|---|
| valueType | Always modeled-sky-brightness. |
| model | APEX model name, profile and model version. |
| requestedMonth | null for the currently supported annual APEX mode. |
| dataset | Annual source dataset identity and period. |
| fallback | Whether source recovery occurred and its source/reason. Separate from the zenith reference fallback. |
| result | alt, az, sqm, bortleClass and bortleDescription for the requested direction. |
| zenithReference | The baseSqm reference, dataset, quality and fallback used alongside the direction. llfcApplied is false. |
{
"apiVersion": "pro-v1",
"requestId": "test",
"latitude": 35.799,
"longitude": 14.588,
"unit": "mag/arcsec²",
"attribution": "darkskysites.com",
"usage": {
"resource": "apex_work_units",
"charged": 1,
"remaining": null,
"resetAt": null
},
"valueType": "modeled-sky-brightness",
"model": {
"name": "APEX",
"profile": "low-replay-v1-volume-1-4-v1",
"version": "apex-native-service-v1"
},
"requestedMonth": null,
"dataset": {"id": "annual_2024", "type": "annual", "period": "2024"},
"fallback": {"used": true, "from": "annual_2025", "reason": "missing_asset"},
"zenithReference": {
"baseSqm": 20.5,
"dataset": {"id": "08_2025", "type": "monthly", "period": "2025-08"},
"llfcApplied": false,
"quality": {
"status": "screened", "method": "seasonal_temporal_v1",
"coverageVerified": false, "flags": []
},
"fallback": {"used": false, "from": null, "reason": null}
},
"result": {
"alt": 15, "az": 240, "sqm": 19.51,
"bortleClass": 7, "bortleDescription": "Suburban/urban transition"
}
}| Field | Description |
|---|---|
| sampling | Either directions with input-order, or horizon with its profile and altitude-then-azimuth ordering. |
| sampleCount | Number of direction results returned. |
| results | Array of alt, az, sqm, bortleClass and bortleDescription values. |
| dataset / model / fallback / zenithReference / usage | Shared APEX provenance and accounting fields described above. |
{
"apiVersion": "pro-v1",
"requestId": "test",
"latitude": 35.799,
"longitude": 14.588,
"unit": "mag/arcsec²",
"attribution": "darkskysites.com",
"usage": {
"resource": "apex_work_units",
"charged": 3,
"remaining": null,
"resetAt": null
},
"valueType": "modeled-sky-brightness",
"model": {
"name": "APEX",
"profile": "low-replay-v1-volume-1-4-v1",
"version": "apex-native-service-v1"
},
"requestedMonth": null,
"dataset": {"id": "annual_2025", "type": "annual", "period": "2025"},
"fallback": {"used": false, "from": null, "reason": null},
"zenithReference": {
"baseSqm": 20.5,
"dataset": {"id": "08_2025", "type": "monthly", "period": "2025-08"},
"llfcApplied": false,
"quality": {
"status": "screened", "method": "seasonal_temporal_v1",
"coverageVerified": false, "flags": []
},
"fallback": {"used": false, "from": null, "reason": null}
},
"sampling": {"mode": "directions", "ordering": "input-order"},
"sampleCount": 3,
"results": [
{"alt": 15, "az": 0, "sqm": 19.51, "bortleClass": 7, "bortleDescription": "Suburban/urban transition"},
{"alt": 30, "az": 90, "sqm": 19.51, "bortleClass": 7, "bortleDescription": "Suburban/urban transition"},
{"alt": 45, "az": 180, "sqm": 19.51, "bortleClass": 7, "bortleDescription": "Suburban/urban transition"}
]
}| Field | Description |
|---|---|
| range | Inclusive from and to months actually returned. |
| correction | Current LLFC policy, revision, asOf timestamp and appliedDelta. This is not a historical reconstruction. |
| data[] | Oldest-first contiguous monthly entries; each is available or unavailable. |
| available entry | month, status, dataset, baseSqm, corrected sqm, Bortle class/description and quality. |
| unavailable entry | month, status, nullable dataset and reason. No other month is substituted. |
| usage | A successful history response is charged as one zenith request, not per returned month. |
{
"apiVersion": "pro-v1",
"requestId": "synthetic-contract-fixture",
"latitude": 35,
"longitude": 14,
"unit": "mag/arcsec²",
"attribution": "darkskysites.com",
"usage": {
"resource": "zenith_requests",
"charged": 1,
"remaining": null,
"resetAt": null
},
"range": {"from": "2025-01", "to": "2025-03"},
"correction": {
"policy": "current-llfc",
"revision": "synthetic-correction-snapshot",
"asOf": "2026-10-15T00:00:00Z",
"appliedDelta": 0.25
},
"data": [
{
"month": "2025-01", "status": "available",
"dataset": {"id": "01_2025", "type": "monthly", "period": "2025-01"},
"baseSqm": 20.5, "sqm": 20.75,
"bortleClass": 5, "bortleDescription": "Suburban sky",
"quality": {
"status": "screened", "method": "seasonal_temporal_v1",
"coverageVerified": false, "flags": []
}
},
{"month": "2025-02", "status": "unavailable", "dataset": null, "reason": "not_published"},
{
"month": "2025-03", "status": "unavailable",
"dataset": {"id": "03_2025", "type": "monthly", "period": "2025-03"},
"reason": "missing_tile"
}
]
}Use time_index to align samples to timeline[] and build altitude, background and optional efficiency chart series. The summary surfaces visible-dark duration, peak altitude/time, background minimum/maximum/brightness ratio, and darkest and highest-efficiency windows. SkyTrack's complete request, response, caveats and runnable client examples are documented above.
| Field | Description |
|---|---|
| schema / timeline | skytrack.v1 contract and one shared chronological UTC timeline with local time, UTC offset and geometric solar state. |
| targets / samples | Fixed-target identity and J2000 coordinates, visibility intervals and physical events; samples retain time_index, geometry and eligibility. |
| environment | Eligible samples include native modeled SQM, darkness index, airmass, extinction, low-altitude caution and background ratio. |
| summary | Per-target qualifying visible-dark duration, peak altitude and time, background minimum/maximum and brightness ratio, darkest positions/windows, and optional highest-efficiency windows. |
| impact | When impact_analysis.enabled=true, eligible samples include conditional efficiency, fixed-time relative SNR and integration-time factor; these are normalized within each target. |
| provenance / usage | Annual dataset and model provenance, disclosed exclusions and existing apex_work_units accounting. Zero eligible directions are charged zero units. |
Preserve quality, dataset, fallback and usage fields when presenting modeled values.
Annual recovery checks at most four published annual sources, newest first. Only missing, corrupt, incomplete or temporarily unavailable source assets trigger an earlier-year attempt; compute, capacity and coverage errors do not.
The annual model uses an independently selected monthly zenith reference, without local LLFC corrections. Its screening and fallback follow the zenith dataset-selection rules, with one retry for a missing tile, invalid sample or storage failure. Source fallback and reference fallback are reported separately.
The optional YYYY-MM month field is reserved in the request schema. Omit it for annual calculations. Exact-month processing does not substitute another month or an annual source.
For APEX requests under custom project policies, work units equal the number of directions divided by the configured directions per unit, rounded up, with a minimum of one unit per request. SkyTrack instead applies the saved account directions-per-unit policy to eligible rays; zero eligible directions cost zero units. Replaying a completed request with the same idempotency key and request parameters returns its receipt without another charge; its usage object records the original charge.
05 / Access, quotas and errors
Pro API access requires an API key with Pro enabled.
Paid Pro allowances are configured per project, separately from the trial below. Check your monthly zenith allowance, APEX work-unit allowance and request limits in the developer dashboard.
New developers can activate a 60-day free Pro trial from their dashboard, with no credit card required.
The trial includes:
Monthly allowances reset on the first day of each month (UTC).
Under the standard trial policy:
Under the standard trial policy, each APEX direction costs one work unit. For example, a horizon profile containing 48 directions uses 48 units. SkyTrack follows the saved directions-per-unit policy and charges zero units when a request has zero eligible rays.
Custom project arrangements may use a different number of directions per unit. Check your project's limits and usage.charged for its accounting.
| Field | Description |
|---|---|
| 400 Ā· INVALID_PARAMETERS | Invalid coordinates, angles, month or request shape. |
| 401 Ā· INVALID_API_KEY | The x-api-key is missing or not valid. |
| 403 Ā· PRO_REQUIRED / API_ACCESS_DENIED | The key lacks the required Pro access or project access is denied. |
| 404 Ā· DATA_UNAVAILABLE | No usable data is available for the requested coverage. |
| 409 Ā· IDEMPOTENCY_CONFLICT / REQUEST_IN_PROGRESS | An idempotency key conflicts with a prior request or an identical request is still running. |
| 413 Ā· PAYLOAD_TOO_LARGE | A request or receipt exceeds a configured bound. |
| 415 Ā· UNSUPPORTED_MEDIA_TYPE | The request body media type is not supported. |
| 422 Ā· UNSUPPORTED_COVERAGE | The requested location is outside the supported raster coverage. |
| 429 Ā· RATE_LIMITED / QUOTA_EXCEEDED | Capacity or the configured project allowance has been reached. Retry guidance may be returned. |
| 500 Ā· INTERNAL_ERROR | The service encountered an unexpected internal error. |
| 503 Ā· DATASET_STORAGE_UNAVAILABLE / CORRECTION_UNAVAILABLE / PRO_UNAVAILABLE / APEX_UNAVAILABLE | Storage, corrections, Pro service or APEX is temporarily unavailable. |
| 504 Ā· HISTORY_TIMEOUT / COMPUTE_TIMEOUT | The history or compute request exceeded its time budget or was cancelled. |
Structured Pro errors include an error message, code, requestId, retryable, retryAfterSeconds and details. Respect retry guidance; do not automatically retry non-retryable input or access errors.
SkyTrack / Part of Pro
SkyTrack combines celestial tracking with DarkSkySites' APEX directional light-pollution model to show how observing conditions change throughout the night. As a target moves, its altitude, atmospheric extinction and exposure to modeled skyglow change with it.
Track up to eight deep-sky objects, examine their paths through modeled skyglow, and identify the darkest and most efficient observing windows. SkyTrack is part of the Pro API for astrophotography planners, observatory software and astronomy applications.
Model, not forecast. SkyTrack uses annual modeled light-pollution conditions. It does not forecast live weather, seeing, Moonlight or date-specific lighting.
Live browser example / no API key
52.5376° N, 1.3474° E · Today at the observing site · M31, M81 and NGC4611 · Natural Sky. Select a target or move the scrubber to update the active-object and imaging-impact readouts.
The interactive sky canvas loads here in the browser. The complete instrument is also available through the link above.
This uses the public browser instrument, not the authenticated Pro API. Its annual light-pollution model is not a live weather or Moon forecast; browser and native numerical parity is not asserted.
POST /api/sqm/skytrack
Pro API Ā· JSON Ā· Schema skytrack.v1
Supply an observing location, a local observing night or UTC interval, and one or more catalogue or J2000 targets. SkyTrack returns a shared astronomical timeline, target positions, eligible directional sky-brightness samples and optional imaging-impact information.
SkyTrack requires a Pro API key and follows the account's existing authentication and work-unit policy. Set DSS_PRO_API_KEY in your server environment and run any one of these examples. Keep keys server-side, never in browser JavaScript, public repositories or URLs.
Each example requests the same local night and M31 target, with impact_analysis.enabled=true to include efficiency and observing windows. The date determines geometry; it does not select date-specific lighting.
# Set DSS_PRO_API_KEY to your Pro key in your server environment.
: "${DSS_PRO_API_KEY:?Set DSS_PRO_API_KEY before running this example}"
curl --fail-with-body --request POST 'https://darkskysites.com/api/sqm/skytrack' \
--header "x-api-key: $DSS_PRO_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"site": {
"latitude_deg": 35.799,
"longitude_deg": 14.588
},
"period": {
"mode": "local_night",
"date": "2026-10-21"
},
"targets": [
{
"client_id": "andromeda",
"catalog_id": "M31"
}
],
"sampling": {
"step_seconds": 600
},
"impact_analysis": {
"enabled": true,
"window_minutes": [
30,
60,
120
],
"reference_sky": {
"mode": "none"
}
}
}'// Node.js 18+. Set DSS_PRO_API_KEY in your server environment.
const apiKey = process.env.DSS_PRO_API_KEY;
if (!apiKey) throw new Error("Set DSS_PRO_API_KEY before running this example");
const request = {
"site": {
"latitude_deg": 35.799,
"longitude_deg": 14.588
},
"period": {
"mode": "local_night",
"date": "2026-10-21"
},
"targets": [
{
"client_id": "andromeda",
"catalog_id": "M31"
}
],
"sampling": {
"step_seconds": 600
},
"impact_analysis": {
"enabled": true,
"window_minutes": [
30,
60,
120
],
"reference_sky": {
"mode": "none"
}
}
};
const response = await fetch("https://darkskysites.com/api/sqm/skytrack", {
method: "POST",
headers: { "Content-Type": "application/json", "x-api-key": apiKey },
body: JSON.stringify(request)
});
const result = await response.json();
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${JSON.stringify(result)}`);
}
console.log(result);# Python 3, standard library only. Set DSS_PRO_API_KEY on your server.
import json
import os
import urllib.error
import urllib.request
payload = json.loads(r'''{
"site": {
"latitude_deg": 35.799,
"longitude_deg": 14.588
},
"period": {
"mode": "local_night",
"date": "2026-10-21"
},
"targets": [
{
"client_id": "andromeda",
"catalog_id": "M31"
}
],
"sampling": {
"step_seconds": 600
},
"impact_analysis": {
"enabled": true,
"window_minutes": [
30,
60,
120
],
"reference_sky": {
"mode": "none"
}
}
}''')
request = urllib.request.Request(
"https://darkskysites.com/api/sqm/skytrack",
data=json.dumps(payload).encode("utf-8"),
headers={
"Content-Type": "application/json",
"x-api-key": os.environ["DSS_PRO_API_KEY"],
},
method="POST",
)
try:
with urllib.request.urlopen(request, timeout=30) as response:
result = json.load(response)
except urllib.error.HTTPError as error:
raise RuntimeError(
f"HTTP {error.code}: {error.read().decode('utf-8')}"
) from error
print(result)Idempotency-Key is optional. If you add it, use 1 to 128 printable non-space ASCII characters, and reuse the same key and unchanged payload for retries of one logical operation. Do not generate a new key for each retry. Use a new key for a different operation.
All targets share one timeline. Each target sample references that timeline through time_index.
Use that index to find a sample's UTC timestamp, then plot geometry.altitude_deg, eligible environment.sqm_mag_arcsec2 and, when enabled, impact.relative_imaging_efficiency. Each target has its own geometry, brightness and observing-window summary; provenance and usage describe the shared computation.
The examples below come from a deterministic API response-builder fixture with synthetic native SQM inputs, not live measurements. To keep the response readable, this fixture uses a separate six-hour UTC interval on the same date and site, with one M31 target and 30-minute sampling. It is not the exact response to the local-night Quick Start.
This excerpt retains timeline indexes 0 through 4 and samples 0 and 4. Later times, other samples and some metadata are omitted. The complete response below contains all 13 timestamps, all 13 samples, target identity, events, visibility intervals, summaries and provenance.
{
"schema": "skytrack.v1",
"requestId": "synthetic-contract-fixture",
"site": {
"latitude_deg": 35.799,
"longitude_deg": 14.588
},
"period": {
"start_utc": "2026-10-21T16:00:00.000Z",
"end_utc": "2026-10-21T22:00:00.000Z",
"time_zone": "Europe/Malta"
},
"timeline": [
{
"utc": "2026-10-21T16:00:00.000Z",
"local_time": "2026-10-21 18:00:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": 2.833467651098677,
"solar_phase": "daylight"
},
{
"utc": "2026-10-21T16:30:00.000Z",
"local_time": "2026-10-21 18:30:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -3.0886301719578753,
"solar_phase": "civil_twilight"
},
{
"utc": "2026-10-21T17:00:00.000Z",
"local_time": "2026-10-21 19:00:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -9.099794532758207,
"solar_phase": "nautical_twilight"
},
{
"utc": "2026-10-21T17:30:00.000Z",
"local_time": "2026-10-21 19:30:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -15.165325762073527,
"solar_phase": "astronomical_twilight"
},
{
"utc": "2026-10-21T18:00:00.000Z",
"local_time": "2026-10-21 20:00:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -21.251555903195257,
"solar_phase": "astronomical_night"
}
],
"targets": [
{
"client_id": "andromeda",
"samples": [
{
"time_index": 0,
"geometry": {
"altitude_deg": 25.191596622224612,
"azimuth_deg": 55.79946079863879,
"above_horizon": true,
"astronomical_darkness": false
},
"eligible": false,
"ineligibility_reason": "NOT_ASTRONOMICAL_NIGHT",
"environment": null,
"impact": null
},
{
"time_index": 4,
"geometry": {
"altitude_deg": 46.443591706892214,
"azimuth_deg": 64.83989350880967,
"above_horizon": true,
"astronomical_darkness": true
},
"eligible": true,
"ineligibility_reason": null,
"environment": {
"valid": true,
"reason": null,
"sqm_mag_arcsec2": 20,
"darkness_index": 47.86127810032719,
"airmass": 1.3784161899728273,
"extinction_mag_total": 0.27568323799456546,
"extinction_mag_vs_zenith": 0.07568323799456547,
"low_altitude_caution": false,
"background_ratio_vs_darkest": 1.0007370987536275
},
"impact": {
"background_ratio_vs_darkest": 1.0007370987536275,
"relative_imaging_efficiency": 0.8711244823365559,
"relative_snr_fixed_time": 0.9333404964623339,
"integration_time_factor": 1.1479415632054908,
"assumed_reference_sky": null
}
}
],
"summary": {
"geometry": {
"qualifying_duration_seconds": 15361.5234375,
"peak_altitude": {
"altitude_deg": 84.38339426745799,
"utc": "2026-10-21T21:44:27.982Z"
},
"reason": null
},
"imaging_impact": {
"model": "faint_source_sky_limited_v1",
"normalization": "within-target-best-sampled-conditions",
"best": {
"utc": "2026-10-21T22:00:00.000Z",
"altitude_deg": 83.61385197113711,
"azimuth_deg": 332.7498573596524,
"sqm_mag_arcsec2": 20.0008
},
"windows": [
{
"minutes": 60,
"window": {
"startMs": 1792616400000,
"endMs": 1792620000000,
"durationMinutes": 60,
"meanBackgroundRatio": 1.0000921097663251,
"meanEfficiency": 0.9989986534893226,
"equivalentReferenceMinutes": 59.93991920935935,
"coverage": 1,
"reference": "within-target-best-sampled-conditions",
"start_utc": "2026-10-21T21:00:00.000Z",
"end_utc": "2026-10-21T22:00:00.000Z"
},
"reason": null
}
]
}
}
}
],
"provenance": {
"dataset": {
"id": "annual_2025",
"type": "annual",
"period": "2025"
},
"annual_model": "Annual light-pollution model, not time-resolved lighting or weather forecast",
"browser_native_parity": "not asserted; browser and native solver profiles can differ"
},
"usage": {
"resource": "apex_work_units",
"charged": 1,
"remaining": null,
"resetAt": null
}
}{
"apiVersion": "pro-v1",
"schema": "skytrack.v1",
"requestId": "synthetic-contract-fixture",
"attribution": "darkskysites.com",
"site": {
"latitude_deg": 35.799,
"longitude_deg": 14.588
},
"period": {
"start_utc": "2026-10-21T16:00:00.000Z",
"end_utc": "2026-10-21T22:00:00.000Z",
"time_zone": "Europe/Malta"
},
"timeline": [
{
"utc": "2026-10-21T16:00:00.000Z",
"local_time": "2026-10-21 18:00:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": 2.833467651098677,
"solar_phase": "daylight"
},
{
"utc": "2026-10-21T16:30:00.000Z",
"local_time": "2026-10-21 18:30:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -3.0886301719578753,
"solar_phase": "civil_twilight"
},
{
"utc": "2026-10-21T17:00:00.000Z",
"local_time": "2026-10-21 19:00:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -9.099794532758207,
"solar_phase": "nautical_twilight"
},
{
"utc": "2026-10-21T17:30:00.000Z",
"local_time": "2026-10-21 19:30:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -15.165325762073527,
"solar_phase": "astronomical_twilight"
},
{
"utc": "2026-10-21T18:00:00.000Z",
"local_time": "2026-10-21 20:00:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -21.251555903195257,
"solar_phase": "astronomical_night"
},
{
"utc": "2026-10-21T18:30:00.000Z",
"local_time": "2026-10-21 20:30:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -27.322891329900056,
"solar_phase": "astronomical_night"
},
{
"utc": "2026-10-21T19:00:00.000Z",
"local_time": "2026-10-21 21:00:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -33.3380689430533,
"solar_phase": "astronomical_night"
},
{
"utc": "2026-10-21T19:30:00.000Z",
"local_time": "2026-10-21 21:30:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -39.244821250273645,
"solar_phase": "astronomical_night"
},
{
"utc": "2026-10-21T20:00:00.000Z",
"local_time": "2026-10-21 22:00:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -44.97163880790057,
"solar_phase": "astronomical_night"
},
{
"utc": "2026-10-21T20:30:00.000Z",
"local_time": "2026-10-21 22:30:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -50.41456940117314,
"solar_phase": "astronomical_night"
},
{
"utc": "2026-10-21T21:00:00.000Z",
"local_time": "2026-10-21 23:00:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -55.41642418854994,
"solar_phase": "astronomical_night"
},
{
"utc": "2026-10-21T21:30:00.000Z",
"local_time": "2026-10-21 23:30:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -59.73792845632541,
"solar_phase": "astronomical_night"
},
{
"utc": "2026-10-21T22:00:00.000Z",
"local_time": "2026-10-22 00:00:00 CEST",
"utc_offset": "GMT+02:00",
"solar_altitude_deg": -63.0340270522663,
"solar_phase": "astronomical_night"
}
],
"targets": [
{
"client_id": "andromeda",
"identity": {
"id": "NGC0224",
"name": "Andromeda Galaxy",
"aliases": [
"NGC0224",
"M31",
"2MASX J00424433+4116074",
"IRAS 00400+4059",
"MCG +07-02-016",
"PGC 002557",
"UGC 00454",
"Andromeda Galaxy"
],
"raDegrees": 10.6847917,
"decDegrees": 41.2690556,
"frame": "equatorial-j2000",
"epoch": 2000,
"origin": {
"catalogue": "OpenNGC",
"version": "be3cd6c5498806a2fbb2f7e0452ef802dbb02be0",
"attribution": "OpenNGC contributors, CC BY-SA 4.0"
}
},
"visibility_intervals": [
{
"start_utc": "2026-10-21T17:43:58.476Z",
"end_utc": "2026-10-21T22:00:00.000Z"
}
],
"events": [
{
"utc": "2026-10-21T16:00:00.000Z",
"kinds": [
"request_boundary"
]
},
{
"utc": "2026-10-21T17:43:58.476Z",
"kinds": [
"dusk"
]
},
{
"utc": "2026-10-21T22:00:00.000Z",
"kinds": [
"request_boundary"
]
}
],
"samples": [
{
"time_index": 0,
"geometry": {
"altitude_deg": 25.191596622224612,
"azimuth_deg": 55.79946079863879,
"above_horizon": true,
"astronomical_darkness": false
},
"eligible": false,
"ineligibility_reason": "NOT_ASTRONOMICAL_NIGHT",
"environment": null,
"impact": null
},
{
"time_index": 1,
"geometry": {
"altitude_deg": 30.315491287314636,
"azimuth_deg": 58.45938152312033,
"above_horizon": true,
"astronomical_darkness": false
},
"eligible": false,
"ineligibility_reason": "NOT_ASTRONOMICAL_NIGHT",
"environment": null,
"impact": null
},
{
"time_index": 2,
"geometry": {
"altitude_deg": 35.58067469823623,
"azimuth_deg": 60.86428522291146,
"above_horizon": true,
"astronomical_darkness": false
},
"eligible": false,
"ineligibility_reason": "NOT_ASTRONOMICAL_NIGHT",
"environment": null,
"impact": null
},
{
"time_index": 3,
"geometry": {
"altitude_deg": 40.96389276331823,
"azimuth_deg": 63.00150684069075,
"above_horizon": true,
"astronomical_darkness": false
},
"eligible": false,
"ineligibility_reason": "NOT_ASTRONOMICAL_NIGHT",
"environment": null,
"impact": null
},
{
"time_index": 4,
"geometry": {
"altitude_deg": 46.443591706892214,
"azimuth_deg": 64.83989350880967,
"above_horizon": true,
"astronomical_darkness": true
},
"eligible": true,
"ineligibility_reason": null,
"environment": {
"valid": true,
"reason": null,
"sqm_mag_arcsec2": 20,
"darkness_index": 47.86127810032719,
"airmass": 1.3784161899728273,
"extinction_mag_total": 0.27568323799456546,
"extinction_mag_vs_zenith": 0.07568323799456547,
"low_altitude_caution": false,
"background_ratio_vs_darkest": 1.0007370987536275
},
"impact": {
"background_ratio_vs_darkest": 1.0007370987536275,
"relative_imaging_efficiency": 0.8711244823365559,
"relative_snr_fixed_time": 0.9333404964623339,
"integration_time_factor": 1.1479415632054908,
"assumed_reference_sky": null
}
},
{
"time_index": 5,
"geometry": {
"altitude_deg": 51.99888607424168,
"azimuth_deg": 66.31692566332293,
"above_horizon": true,
"astronomical_darkness": true
},
"eligible": true,
"ineligibility_reason": null,
"environment": {
"valid": true,
"reason": null,
"sqm_mag_arcsec2": 20.0001,
"darkness_index": 47.8630414940143,
"airmass": 1.26798101827545,
"extinction_mag_total": 0.25359620365509,
"extinction_mag_vs_zenith": 0.05359620365509002,
"low_altitude_caution": false,
"background_ratio_vs_darkest": 1.0006449317051185
},
"impact": {
"background_ratio_vs_darkest": 1.0006449317051185,
"relative_imaging_efficiency": 0.9073813463163745,
"relative_snr_fixed_time": 0.9525656650942099,
"integration_time_factor": 1.1020724682732594,
"assumed_reference_sky": null
}
},
{
"time_index": 6,
"geometry": {
"altitude_deg": 57.60787928480533,
"azimuth_deg": 67.31253320884338,
"above_horizon": true,
"astronomical_darkness": true
},
"eligible": true,
"ineligibility_reason": null,
"environment": {
"valid": true,
"reason": null,
"sqm_mag_arcsec2": 20.0002,
"darkness_index": 47.864804952671605,
"airmass": 1.1834792654981903,
"extinction_mag_total": 0.23669585309963806,
"extinction_mag_vs_zenith": 0.036695853099638055,
"low_altitude_caution": false,
"background_ratio_vs_darkest": 1.0005527731451174
},
"impact": {
"background_ratio_vs_darkest": 1.0005527731451174,
"relative_imaging_efficiency": 0.9361601004481892,
"relative_snr_fixed_time": 0.9675536679937652,
"integration_time_factor": 1.0681933565863866,
"assumed_reference_sky": null
}
},
{
"time_index": 7,
"geometry": {
"altitude_deg": 63.24433526087191,
"azimuth_deg": 67.59017651091057,
"above_horizon": true,
"astronomical_darkness": true
},
"eligible": true,
"ineligibility_reason": null,
"environment": {
"valid": true,
"reason": null,
"sqm_mag_arcsec2": 20.0003,
"darkness_index": 47.866568476301524,
"airmass": 1.119287011166149,
"extinction_mag_total": 0.2238574022332298,
"extinction_mag_vs_zenith": 0.02385740223322981,
"low_altitude_caution": false,
"background_ratio_vs_darkest": 1.0004606230728426
},
"impact": {
"background_ratio_vs_darkest": 1.0004606230728426,
"relative_imaging_efficiency": 0.9586517911845952,
"relative_snr_fixed_time": 0.9791076504575966,
"integration_time_factor": 1.0431316242202096,
"assumed_reference_sky": null
}
},
{
"time_index": 8,
"geometry": {
"altitude_deg": 68.86958930339127,
"azimuth_deg": 66.64642993595965,
"above_horizon": true,
"astronomical_darkness": true
},
"eligible": true,
"ineligibility_reason": null,
"environment": {
"valid": true,
"reason": null,
"sqm_mag_arcsec2": 20.0004,
"darkness_index": 47.86833206490644,
"airmass": 1.0715875327051403,
"extinction_mag_total": 0.21431750654102807,
"extinction_mag_vs_zenith": 0.014317506541028058,
"low_altitude_caution": false,
"background_ratio_vs_darkest": 1.000368481487512
},
"impact": {
"background_ratio_vs_darkest": 1.000368481487512,
"relative_imaging_efficiency": 0.9757370692887091,
"relative_snr_fixed_time": 0.9877940419382519,
"integration_time_factor": 1.0248662590312143,
"assumed_reference_sky": null
}
},
{
"time_index": 9,
"geometry": {
"altitude_deg": 74.40799405147379,
"azimuth_deg": 63.25740560776569,
"above_horizon": true,
"astronomical_darkness": true
},
"eligible": true,
"ineligibility_reason": null,
"environment": {
"valid": true,
"reason": null,
"sqm_mag_arcsec2": 20.0005,
"darkness_index": 47.87009571848874,
"airmass": 1.0377911660229,
"extinction_mag_total": 0.20755823320458,
"extinction_mag_vs_zenith": 0.007558233204580001,
"low_altitude_caution": false,
"background_ratio_vs_darkest": 1.0002763483883446
},
"impact": {
"background_ratio_vs_darkest": 1.0002763483883446,
"relative_imaging_efficiency": 0.9880529593791043,
"relative_snr_fixed_time": 0.9940085308381937,
"integration_time_factor": 1.012091498241555,
"assumed_reference_sky": null
}
},
{
"time_index": 10,
"geometry": {
"altitude_deg": 79.6485354851572,
"azimuth_deg": 53.79068269038419,
"above_horizon": true,
"astronomical_darkness": true
},
"eligible": true,
"ineligibility_reason": null,
"environment": {
"valid": true,
"reason": null,
"sqm_mag_arcsec2": 20.0006,
"darkness_index": 47.87185943705084,
"airmass": 1.0161866254477623,
"extinction_mag_total": 0.20323732508955247,
"extinction_mag_vs_zenith": 0.0032373250895524567,
"low_altitude_caution": false,
"background_ratio_vs_darkest": 1.0001842237745582
},
"impact": {
"background_ratio_vs_darkest": 1.0001842237745582,
"relative_imaging_efficiency": 0.9960403902443494,
"relative_snr_fixed_time": 0.9980182314188201,
"integration_time_factor": 1.0039753505926392,
"assumed_reference_sky": null
}
},
{
"time_index": 11,
"geometry": {
"altitude_deg": 83.71053254146848,
"azimuth_deg": 25.65738881411295,
"above_horizon": true,
"astronomical_darkness": true
},
"eligible": true,
"ineligibility_reason": null,
"environment": {
"valid": true,
"reason": null,
"sqm_mag_arcsec2": 20.0007,
"darkness_index": 47.87362322059511,
"airmass": 1.005729688459483,
"extinction_mag_total": 0.20114593769189662,
"extinction_mag_vs_zenith": 0.0011459376918966147,
"low_altitude_caution": false,
"background_ratio_vs_darkest": 1.0000921076453715
},
"impact": {
"background_ratio_vs_darkest": 1.0000921076453715,
"relative_imaging_efficiency": 0.9999771118564702,
"relative_snr_fixed_time": 0.9999885558627509,
"integration_time_factor": 1.000022888667409,
"assumed_reference_sky": null
}
},
{
"time_index": 12,
"geometry": {
"altitude_deg": 83.61385197113711,
"azimuth_deg": 332.7498573596524,
"above_horizon": true,
"astronomical_darkness": true
},
"eligible": true,
"ineligibility_reason": null,
"environment": {
"valid": true,
"reason": null,
"sqm_mag_arcsec2": 20.0008,
"darkness_index": 47.87538706912402,
"airmass": 1.0059175615332785,
"extinction_mag_total": 0.2011835123066557,
"extinction_mag_vs_zenith": 0.0011835123066556985,
"low_altitude_caution": false,
"background_ratio_vs_darkest": 1
},
"impact": {
"background_ratio_vs_darkest": 1,
"relative_imaging_efficiency": 1,
"relative_snr_fixed_time": 1,
"integration_time_factor": 1,
"assumed_reference_sky": null
}
}
],
"summary": {
"geometry": {
"qualifying_duration_seconds": 15361.5234375,
"peak_altitude": {
"altitude_deg": 84.38339426745799,
"utc": "2026-10-21T21:44:27.982Z"
},
"reason": null
},
"sky_background": {
"valid_samples": 9,
"min_sqm": 20,
"max_sqm": 20.0008,
"range_mag": 0.0008000000000016882,
"brightest_darkest_ratio": 1.0007370987536275,
"darkest": {
"utc": "2026-10-21T22:00:00.000Z",
"altitude_deg": 83.61385197113711,
"azimuth_deg": 332.7498573596524,
"sqm_mag_arcsec2": 20.0008
},
"brightest": {
"utc": "2026-10-21T18:00:00.000Z",
"altitude_deg": 46.443591706892214,
"azimuth_deg": 64.83989350880967,
"sqm_mag_arcsec2": 20
},
"darkest_windows": [
{
"minutes": 60,
"window": {
"startMs": 1792616400000,
"endMs": 1792620000000,
"durationMinutes": 60,
"meanBackgroundRatio": 1.0000921097663251,
"meanEfficiency": 0.9989986534893226,
"equivalentReferenceMinutes": 59.93991920935935,
"coverage": 1,
"reference": "within-target-best-sampled-conditions",
"start_utc": "2026-10-21T21:00:00.000Z",
"end_utc": "2026-10-21T22:00:00.000Z"
},
"reason": null
}
]
},
"imaging_impact": {
"model": "faint_source_sky_limited_v1",
"normalization": "within-target-best-sampled-conditions",
"best": {
"utc": "2026-10-21T22:00:00.000Z",
"altitude_deg": 83.61385197113711,
"azimuth_deg": 332.7498573596524,
"sqm_mag_arcsec2": 20.0008
},
"windows": [
{
"minutes": 60,
"window": {
"startMs": 1792616400000,
"endMs": 1792620000000,
"durationMinutes": 60,
"meanBackgroundRatio": 1.0000921097663251,
"meanEfficiency": 0.9989986534893226,
"equivalentReferenceMinutes": 59.93991920935935,
"coverage": 1,
"reference": "within-target-best-sampled-conditions",
"start_utc": "2026-10-21T21:00:00.000Z",
"end_utc": "2026-10-21T22:00:00.000Z"
},
"reason": null
}
]
}
}
}
],
"provenance": {
"geometry_convention": "J2000 mean equatorial; IAU-1976 precession to mean equator/equinox of date; mean sidereal time; geometric horizon; no refraction, proper motion, target aberration or nutation. UTC approximates UT1.",
"model": {
"name": "APEX",
"profile": "low-replay-v1-volume-1-4-v1",
"version": "apex-native-service-v1"
},
"effective_voxel_resolution": [
20,
20,
10
],
"dataset": {
"id": "annual_2025",
"type": "annual",
"period": "2025"
},
"fallback": {
"used": false,
"from": null,
"reason": null
},
"zenith_reference": {
"baseSqm": 20.5,
"dataset": {
"id": "08_2025",
"type": "monthly",
"period": "2025-08"
},
"llfcApplied": false,
"quality": {
"status": "screened",
"method": "seasonal_temporal_v1",
"coverageVerified": false,
"flags": []
},
"fallback": {
"used": false,
"from": null,
"reason": null
}
},
"source_key": "d7cc37f33d9445500f0d96033963c369dbf25484cacdea1ff724ee057a66c5f5",
"source_completeness": "complete-authoritative-native-patch",
"native_identities": {
"source": null,
"field": null,
"profile": null,
"patch_sha256": null,
"asset_manifest": null
},
"calibration": "existing-native-APEX-SQM",
"sampling_method": "native-directional-readback; raw SQM before public display rounding",
"source_corrections": {
"llfc_applied": false,
"other_corrections": "unknown"
},
"extinction": {
"coefficient_mag_per_airmass": 0.2,
"formula": "Kasten-Young airmass; total=k*X; zenith-relative=k*(X-1); T=10^(-0.4*k*(X-1))"
},
"impact_model": "faint_source_sky_limited_v1",
"impact_assumptions": "Faint-source, sky-background-limited estimate. Same target, telescope, camera, filter and configuration. Assumed attenuation, not measured transparency. Excludes read noise, dark current, seeing, Moon, clouds, guiding, saturation and target spectra. SQM-compatible proxy is not a validated narrowband response.",
"interpolation": "piecewise-linear B and Q within valid adjacent samples, at requested cadence up to 30 minutes; no extrapolation",
"artificial_light_separation": "unsupported",
"annual_model": "Annual light-pollution model, not time-resolved lighting or weather forecast",
"browser_native_parity": "not asserted; browser and native solver profiles can differ",
"exclusions": [
"Moon",
"weather",
"seeing",
"terrain",
"moving Solar System objects",
"daylight/twilight photometry"
]
},
"computation": {
"eligible_directions": 9,
"field_batches": 1
},
"usage": {
"resource": "apex_work_units",
"charged": 1,
"remaining": null,
"resetAt": null
}
}Run this after the JavaScript first-request example. Keep unavailable or ineligible values as null, not zero. Geometry can still be plotted when photometry is ineligible. A missing impact value may simply mean impact analysis was disabled.
// result is the JSON returned by the first-request example.
const tracks = result.targets.map(target => ({
clientId: target.client_id,
points: target.samples.map(sample => {
const time = result.timeline[sample.time_index];
const valid = sample.eligible && sample.environment?.valid === true;
return {
utc: time.utc,
altitudeDeg: sample.geometry.altitude_deg,
sqm: valid ? sample.environment.sqm_mag_arcsec2 : null,
efficiency: valid
? (sample.impact?.relative_imaging_efficiency ?? null)
: null
};
})
}));
// Keep nulls as gaps. Disable "connect nulls" in your chart library.
// Do not interpolate across missing samples or gaps longer than 30 minutes.
console.log(tracks);Do not connect null points or bridge gaps. Native summaries interpolate only adjacent valid samples at the requested cadence, with a maximum 30-minute gap; sampling more coarsely can leave window results unavailable. A window: null includes a reason, not a zero-duration observation.
Send one JSON body to POST /api/sqm/skytrack. Unknown fields, unsupported coordinate frames and query-string parameters are rejected; supply all observing parameters in the body.
/api/sqm/skytrackPro accessCalculate target positions, astronomical-darkness visibility and annual-model sky brightness along a shared observing timeline, with optional conditional imaging efficiency and observing windows.
JSON body only; up to 8 fixed targets, 200 timestamps, 1000 eligible directions and 25 hours. API-key authentication is required. Zero eligible directions cost zero work units; other results use the saved directions-per-unit policy. The observing date changes the geometry, not the annual light-pollution dataset into a weather or date-specific lighting forecast.
Use geographic coordinates in decimal degrees. Eligible directional evaluation requires existing native raster coverage.
| Field | Description |
|---|---|
| site.latitude_deg | Required finite number, -90 to 90 inclusive. |
| site.longitude_deg | Required finite number, -180 to 180 inclusive. |
Choose a local civil observing night or an explicit UTC interval. Both resolve to one shared timeline, with a maximum duration of 25 hours.
| Field | Description |
|---|---|
| period.mode = local_night | Supply date as a valid YYYY-MM-DD civil date, 1900 to 2100. The interval runs from local noon to the following local noon, preserving daylight-saving transitions. |
| period.mode = utc_interval | Supply start_utc and end_utc as UTC ISO timestamps ending in Z, within supported dates. The end must follow the start; the interval cannot exceed 25 hours. |
| Time zone | Inferred from the observing coordinates, not a supplied timezone field. The response period.time_zone is an IANA timezone; timeline local_time and utc_offset disclose each timestamp's local representation. |
Track fixed deep-sky objects. Returned targets retain input order; moving Solar System targets are not supported.
| Field | Description |
|---|---|
| targets | Required array of 1 to 8 targets. Each client_id must be unique after trimming. |
| targets[].client_id | Required string, 1 to 80 characters after trimming. Use it to match returned targets to your application. |
| targets[].catalog_id | Catalogue identifier, 1 to 100 characters after trimming. OpenNGC aliases are accepted. Unknown or ambiguous identifiers, including M102, require explicit coordinates. |
| targets[].coordinates | Supply exactly one of catalog_id or coordinates. Manual coordinates require finite ra_deg in [0,360), dec_deg in [-90,90], and frame = J2000_MEAN_EQUATORIAL. |
The service rejects excessive work rather than silently coarsening your requested sampling.
| Field | Description |
|---|---|
| sampling.step_seconds | Integer, default 600, minimum 120, maximum 90000 seconds. Both period boundaries are included. |
| Timeline / directions | At most 200 shared timestamps and 1,000 eligible directions across all targets. Existing operator-configured batch caps can reduce the eligible-direction ceiling. |
| Body / headers | Content-Type: application/json. At most 96 KiB after decompression. Authenticate with x-api-key; never put keys in URLs. |
| Idempotency-Key | Optional, 1 to 128 printable non-space ASCII characters. Reuse the same key and unchanged payload when retrying one logical operation. |
Omitting impact_analysis disables it. Set enabled=true explicitly to request conditional efficiency and observing windows; set enabled=false explicitly to disable it when supplying the object.
| Field | Description |
|---|---|
| impact_analysis.enabled | Boolean. An omitted impact_analysis object defaults to disabled; within a supplied object, enabled defaults to true. Always set it explicitly for clarity. |
| impact_analysis.window_minutes | Array of 1 to 3 entries chosen from 30, 60 and 120; default [30,60,120]. Short or non-contiguous eligible coverage can make a window unavailable. |
| impact_analysis.reference_sky | Defaults to {mode: none}. Alternatively, use mode: assumed_reference with finite sqm_mag_arcsec2 from 0 to 30 inclusive. This is a conditional assumed magnitude proxy, not a measured pristine baseline. |
Use this full request body with the same endpoint and authentication as the Quick Start.
{
"site": {
"latitude_deg": 35.799,
"longitude_deg": 14.588
},
"period": {
"mode": "local_night",
"date": "2026-10-21"
},
"targets": [
{
"client_id": "andromeda",
"catalog_id": "M31"
},
{
"client_id": "pleiades",
"catalog_id": "M45"
},
{
"client_id": "custom",
"coordinates": {
"ra_deg": 10.6847,
"dec_deg": 41.2688,
"frame": "J2000_MEAN_EQUATORIAL"
}
}
],
"sampling": {
"step_seconds": 600
},
"impact_analysis": {
"enabled": true,
"window_minutes": [
30,
60,
120
],
"reference_sky": {
"mode": "none"
}
}
}Or replace only the period object with an explicit UTC interval:
{
"mode": "utc_interval",
"start_utc": "2026-10-21T18:00:00Z",
"end_utc": "2026-10-22T04:00:00Z"
}One chronological UTC axis serves every target. Join samples through time_index, not by assuming that an eligible-only array has the same indexes.
| Field | Description |
|---|---|
| apiVersion / schema / requestId | pro-v1 / skytrack.v1 / stable receipt ID. Attribution is darkskysites.com. |
| site / period | Input latitude_deg and longitude_deg; resolved start_utc, end_utc and IANA time_zone. |
| timeline[] | utc, local_time, utc_offset, solar_altitude_deg and solar_phase. Solar altitude is geometric under the existing DSS astronomy convention, not a twilight-brightness prediction. |
| targets[].identity | Canonical target identity and J2000 coordinates, including id, name, aliases, raDegrees, decDegrees, frame, epoch and catalogue origin. Response identity uses the equatorial-j2000 frame label. |
| targets[].samples[].time_index | Zero-based index into timeline[]. Every timestamp is retained for each target, including ineligible samples. |
Geometry remains useful even when the Sun or target position makes a directional sky-brightness sample ineligible.
| Field | Description |
|---|---|
| targets[].visibility_intervals / events | Exact qualifying visible-dark intervals and physical rise/set/dusk/dawn events. Clipped interval edges are labelled request_boundary, not invented physical events. |
| samples[].geometry | altitude_deg and azimuth_deg in degrees; above_horizon and astronomical_darkness booleans. |
| samples[].eligible / ineligibility_reason | Eligible requires geometric target altitude >0 degrees and Sun altitude <=-18 degrees. Otherwise environment and impact are null, with an ineligibility_reason. |
| summary.geometry | qualifying_duration_seconds; peak_altitude with altitude_deg and utc; reason when applicable. |
Only eligible samples receive native directional photometry. No client-supplied SQM or display-RGB inference is used.
| Field | Description |
|---|---|
| samples[].environment | valid and reason; sqm_mag_arcsec2 in mag/arcsec² and the existing darkness_index. Higher SQM means a darker modeled sky. |
| environment.airmass / extinction | airmass is dimensionless. extinction_mag_total and extinction_mag_vs_zenith are magnitudes; low_altitude_caution flags the model's low-altitude caution. |
| environment.background_ratio_vs_darkest | Dimensionless sky-background ratio relative to this target's darkest valid sampled background. A value above 1 means brighter, not darker. |
| summary.sky_background | valid_samples, min_sqm, max_sqm, range_mag, brightest_darkest_ratio, darkest and brightest positions, and darkest_windows. Positions contain utc, altitude_deg, azimuth_deg and sqm_mag_arcsec2. |
Impact is optional and normalized within each target. It does not provide an absolute cross-target signal-to-noise ranking.
| Field | Description |
|---|---|
| samples[].impact | When enabled and valid: background_ratio_vs_darkest, relative_imaging_efficiency, relative_snr_fixed_time, integration_time_factor and optional assumed_reference_sky. Otherwise null. |
| summary.imaging_impact | model, normalization, best position and windows for requested 30/60/120-minute durations. Null when impact analysis is disabled. |
| Window records | Each has minutes, window and reason. A valid window includes start_utc/end_utc, startMs/endMs (Unix milliseconds), durationMinutes, meanBackgroundRatio, meanEfficiency, equivalentReferenceMinutes, coverage and reference. Unavailable windows have window: null with a reason. |
| Window comparison | Compare the same requested duration. Darkest windows minimize mean background; highest-efficiency windows maximize equivalent reference minutes for that duration. They need not start at the same time. |
Keep the returned provenance with exported or cached results so the model and its limitations remain identifiable.
| Field | Description |
|---|---|
| provenance.model / effective_voxel_resolution | Actual native solver profile and voxel resolution, not the public browser renderer profile. |
| dataset / fallback / zenith_reference | Enabled annual source dataset, disclosed source fallback and authoritative zenith reference. These belong within provenance. |
| source_key / native_identities / source_completeness | Native field/source/profile, patch and asset identities when available, and source completeness. Zero-eligible-ray requests disclose that no native field was evaluated. |
| calibration / sampling_method / source_corrections | Existing native APEX SQM calibration, raw directional readback before public display rounding, and correction state. |
| extinction / impact_model / impact_assumptions | Extinction coefficient/formula, conditional analysis model and its assumptions. |
| interpolation / exclusions | Interpolation policy, annual_model, unsupported artificial_light_separation and exclusions. browser_native_parity is not asserted; browser and native solver profiles can differ. |
Read the actual returned receipt, not an assumed trial or project allowance.
| Field | Description |
|---|---|
| usage | resource: apex_work_units; charged; actual remaining headroom and resetAt. Null balances or reset times mean they are not provided, not zero allowance. |
| computation | eligible_directions and field_batches. Eligible native directions are evaluated in one complete batch; geometry-only requests have no native field batch. |
The model combines target geometry, directional modeled sky brightness and atmospheric extinction to estimate relative imaging conditions. Relative imaging efficiency is normalized within each target's track: it is not a validated absolute signal-to-noise measurement or a comparison of the intrinsic imaging difficulty of different targets.
Annual modeled light pollution is not a forecast of live weather, Moonlight, seeing or date-specific lighting. These are faint-source, sky-background-limited planning estimates, not measured camera performance.
B = 10^(-0.4 m)
background ratio = 10^(0.4(m_darkest - m))
T = 10^(-0.4 k(X - 1))
Q = T² / B
efficiency = Q / max(Q)
relative fixed-time SNR = sqrt(efficiency)
integration-time factor = 1 / efficiency
k = 0.20 mag/airmassm is directional SQM, X is existing Kasten-Young airmass, and T is transmission relative to zenith under the assumed extinction coefficient. Total extinction is kX; zenith-relative extinction is k(X-1).
Reference-equivalent minutes integrate normalized Q over time. Piecewise-linear B and Q are integrated only between adjacent valid samples at the requested cadence, with a maximum 30-minute interpolation gap. There is no extrapolation. Gaps and invalid samples are never bridged; ties select the earliest start.
The model assumes the same target, equipment, filter and attenuation. It has no validated narrowband response, natural/artificial separation, Moon, weather, date-specific lighting, seeing, terrain, read noise, dark current, guiding or saturation model. Moving Solar System targets and daylight/twilight photometry are excluded.
An explicitly assumed reference sky is a conditional magnitude-proxy comparison, not a measured pristine baseline or pollution percentage. Annual source data is not a time-resolved lighting forecast. Browser/native solver parity is not asserted.
SkyTrack consumes APEX work units using the project's saved directions-per-unit policy: eligible directions divided by directions per unit, rounded up. Zero eligible directions consume zero units, although authentication and rate/concurrency rules still apply. Do not apply the minimum-one-unit wording for other Pro request types to a zero-ray SkyTrack request.
A completed batch is charged once. Failures release reservations; partial native batches are not returned. Replaying a completed partner-scoped request with the same idempotency key and unchanged parameters returns the stored receipt without recomputation or another charge; its usage records the original charge. Receipt retention follows existing operator settings, not a new caching or commercial guarantee.
Errors return error, code, requestId, retryable, retryAfterSeconds and details. Follow those retry fields and Retry-After when supplied, with bounded backoff. Do not blindly retry invalid requests, authentication failures or unsupported coverage. Source and worker failures do not expose internal paths or exceptions.
| Status / code | Meaning | Developer action |
|---|---|---|
| 400 Ā· INVALID_PARAMETERS | Invalid body, target, interval, frame or idempotency key. | Correct the request before retrying. |
| 401 Ā· INVALID_API_KEY | Missing or invalid x-api-key. | Check the server-side credential. |
| 403 Ā· PRO_REQUIRED | The key lacks active Pro access. | Check the account's Pro entitlement. |
| 404 Ā· DATA_UNAVAILABLE | No usable source data. | Check coverage/data availability; do not plot invented values. |
| 409 Ā· IDEMPOTENCY_CONFLICT | The key was used with a different payload or operation. | Use a new key only for a different logical operation. |
| 409 Ā· REQUEST_IN_PROGRESS | The same logical request is still running. | Wait, then retry the same payload and idempotency key. |
| 413 Ā· PAYLOAD_TOO_LARGE | Body or receipt exceeds an applicable bound. | Reduce the request size or work requested. |
| 415 Ā· UNSUPPORTED_MEDIA_TYPE | Unsupported request media type. | Send application/json. |
| 422 Ā· UNSUPPORTED_COVERAGE | The site is outside supported raster coverage. | Use a supported site; do not repeatedly retry unchanged. |
| 429 Ā· RATE_LIMITED / QUOTA_EXCEEDED | Capacity, rate/concurrency or saved allowance reached. | Follow retry guidance; check allowance/reset before retrying quota errors. |
| 503 Ā· PRO_UNAVAILABLE / APEX_UNAVAILABLE | Pro admission or native computation is unavailable. | Respect retryable and retry guidance; keep the logical operation's key. |
| 504 Ā· COMPUTE_TIMEOUT | The computation deadline or connection was exceeded. | Use bounded retries according to the returned guidance. |