Light Pollution API Reference

DarkSkySites.com

DarkSkySites / Developer platform

Light Pollution API

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

A sky model for location-aware software

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

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.

02

Plan Milky Way photography

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

Find bright horizons and darker sectors

Sample low-altitude compass directions to characterize light domes, identify relatively dark sectors and compare them with nearby city directions.

04

Compare observing locations

Query target-relevant directions at multiple sites to find potentially better locations for a specific observation, rather than comparing zenith SQM alone.

05

Plan fixed-target observing windows

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

Test an API query

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.

Enable JavaScript to run an interactive API query.

The copied example uses the production API endpoint, which requires your own 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

Explore brightness around the horizon

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

Test a Directional API Query

Enable JavaScript to search places, submit queries and render the sky canvas.

Directional: not requestedZenith: not requested

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

Choose the data your application needs

CapabilityFreePro
Zenith SQM and Bortle estimateIncludedIncluded
Directional sky brightnessNot includedBy altitude and azimuth
Monthly Zenith historyNot includedExact calendar-month entries
Fixed-target timelinesNot includedFull DSO tracks via SkyTrack
Standard limits30,000 / month, 10 / second, 3 active keysSee Pro quotas

Free / API documentation

Zenith SQM and Bortle

The Free API returns modeled sky brightness directly overhead, with the selected dataset and quality details required to interpret it. Send requests from a server-side application and keep the API key out of browser code.

01 / Authentication and first request

Send a server-side 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
curl --get 'https://darkskysites.com/api/sqm' \
  --data-urlencode 'lat=35.2401' \
  --data-urlencode 'lng=14.4378' \
  --header 'x-api-key: YOUR_API_KEY'
Node.js
// 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);
Python
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

A modeled value with source context

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

GET /api/sqm

GET/api/sqmFree access

Latest modeled Zenith

Returns the latest usable zenith SQM and its SQM-derived Bortle class, with dataset and quality information.

Request example
GET /api/sqm?lat=35.799&lng=14.588

Required 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.

Free Zenith request parameters
FieldDescription
latRequired. Decimal latitude from -90 through 90.
lngRequired. Decimal longitude from -180 through 180.
dateOptional 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

Returned response shape

This is the published sample response. Values depend on the requested location and selected source dataset.

JSON sample
{
  "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"
}
Free response fields
FieldDescription
latitude / longitudeObserver coordinates returned as decimal degrees.
sqmModeled zenith brightness in mag/arcsec². Higher values mean a darker modeled sky. This is not a live meter reading.
bortleClass / bortleDescriptionA classification derived from returned SQM, not an observed visual class.
dataset.id / year / monthSelected source dataset identifier, year and month, requestedDate, fallbackUsed, fallbackFrom, fallbackReason and datasetsChecked.
qualitystatus, method, coverageVerified and screening flags. coverageVerified is always false.
attributionRequired source attribution string, darkskysites.com.

05 / DATASET SELECTION AND QUALITY

Dataset selection and quality

DarkSkySites selects the latest usable monthly dataset and includes its source and quality information in the response.

Automatic selection

Without date, the API checks enabled datasets from newest to oldest and returns the first usable result.

Dataset fallback

If the requested month is unavailable, the API searches earlier datasets and identifies the month returned. Read dataset.id for that month.

Dataset response fields
FieldMeaning
dataset.idMonth returned, formatted MM_YYYY.
dataset.year / dataset.monthYear and month returned.
dataset.requestedDateRequested date, or null if omitted.
dataset.fallbackUsedTrue when returned ID differs from the requested month normalized to MM_YYYY, or the latest candidate when date is omitted.
dataset.fallbackFromComparison month when different from the returned month; otherwise null.
dataset.fallbackReasonFirst reason the comparison month was skipped, or null.
dataset.datasetsCheckedDistinct datasets evaluated, including comparison checks.

Data quality

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.");
}

Data provenance

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.

Technical details

Quality fields

Quality response fields
FieldMeaning
quality.statusscreened, unverified_zero, or unavailable on no-result errors.
quality.methodRule version: seasonal_temporal_v1.
quality.coverageVerifiedAlways false; source coverage cannot be verified.
quality.flagsScreening reasons, including zero_brightness_unverified when applicable.

Screening and search bounds

  • The search checks at most 12 enabled candidate datasets, not 12 calendar months. Zero comparisons share this window and can increase datasetsChecked without changing fallbackUsed.
  • May through July are excluded north of 55°N. April, August, and September are also excluded north of 70°N.
  • April through September north of 55°N, reject zero only if two older October through March samples in-window have base SQM ≤19.00; otherwise retain it as unverified_zero.
  • Missing or invalid samples are skipped. Screening uses source values before local LLFC corrections. A zero value alone does not establish missing data.

Fallback reason codes

dataset_unavailable
Month not published or enabled.
seasonal_exclusion
Month excluded at this latitude.
suspect_seasonal_zero
Older months suggest a seasonal data gap.
missing_tile
No source tile for this location and month.
invalid_sample
Source sample is unusable.
storage_unavailable
Source data unavailable.
outside_dataset_extent
Location outside dataset extent.

05 / Limits and errors

Standard Free project limits

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.

Free API error status reference
FieldDescription
400Invalid coordinates or date format.
401Missing or invalid API key.
403Project access is suspended, revoked or does not include the requested access.
404No usable dataset was found within the bounded candidate search.
429Request rate or monthly allowance reached. Observe any retry guidance.
503Data, storage or service capacity is temporarily unavailable. Retry later.

06 / Attribution

Credit the data where it appears

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

Create an API key

Free self-service access requires an account and project activation in the developer dashboard. No credit card is required.

Pro / API documentation

Directional APEX and monthly history

Use APEX to query modeled brightness at specific sky coordinates, request monthly zenith history, or use SkyTrack to map fixed-target observing timelines with a Pro API key. Paid Pro includes 50,000 APEX work units per month; the Pro trial includes 5,000 per month. Responses include source datasets, quality information and usage accounting.

APEX uses annual datasets. Monthly directional queries are not currently supported.

01 / Single-direction request

Model brightness in any direction

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.

GET/api/sqm/directionalPro access

Single-direction APEX

Computes 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.

Directional request parameters
FieldDescription
latRequired. Observer latitude, -90 through 90 degrees.
lngRequired. Observer longitude, -180 through 180 degrees.
altRequired. Angular elevation above the horizon, 0 through 90 degrees. 0 is the horizon; 90 is zenith.
azRequired. 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-keyRequired 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.

directional cURL
curl 'https://darkskysites.com/api/sqm/directional?lat=40.8366&lng=-105.2052&alt=25&az=90' \
  --header 'x-api-key: YOUR_API_KEY'
directional JavaScript
// 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);
directional Python
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 multiple directions in one request

Calculate sky brightness for multiple directions with a single API request. You can either:

  • Specify directions: Provide a list of altitude and azimuth coordinates. Results are returned in the same order, including any repeated directions.
  • Generate a horizon profile: Automatically sample the sky at regular azimuth intervals, covering a full 360° without repeating the starting point.

Choose one method per request. The maximum number of directions depends on your account's API limits.

POST/api/sqm/directionsPro access

Directional array or horizon profile

Submit 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.

Batch request fields
FieldDescription
latitude / longitudeRequired 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.typeRequired literal "horizon" when using a generated profile.
profile.azimuthStepInteger 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-Keyx-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.

batch cURL
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
    }
  ]
}'
batch JavaScript
// 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);
batch Python
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)

Evaluate a horizon profile

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.

horizon cURL
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
    ]
  }
}'
horizon JavaScript
// 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);
horizon Python
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

Turn the monthly record into a trend

Historical zenith SQM can help show whether a location has become brighter or darker and how modeled light pollution has changed over time.

GET/api/sqm/historyPro access

Monthly Zenith history

Returns 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.

History request parameters
FieldDescription
latRequired. Latitude from -90 through 90 degrees.
lngRequired. Longitude from -180 through 180 degrees.
fromOptional start month, YYYY-MM. If both bounds are given, from must not be later than to.
toOptional end month, YYYY-MM. Future months are not supported.
x-api-key / Idempotency-Keyx-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.

history cURL
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'
history JavaScript
// 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);
history Python
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

Read values with their provenance

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.

Common response fields

Common Pro response fields
FieldDescription
apiVersionThe response contract identifier, pro-v1.
requestIdIdentifier for this request or replayed receipt.
latitude / longitudeObserver coordinates in decimal degrees.
unitModeled brightness unit, mag/arcsec².
attributionRequired attribution string, darkskysites.com.
usageResource charged, units charged, remaining allowance when known, and resetAt when known.

Single-direction response

Directional response fields
FieldDescription
valueTypeAlways modeled-sky-brightness.
modelAPEX model name, profile and model version.
requestedMonthnull for the currently supported annual APEX mode.
datasetAnnual source dataset identity and period.
fallbackWhether source recovery occurred and its source/reason. Separate from the zenith reference fallback.
resultalt, az, sqm, bortleClass and bortleDescription for the requested direction.
zenithReferenceThe baseSqm reference, dataset, quality and fallback used alongside the direction. llfcApplied is false.
JSON Ā· single directional response
{
  "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"
  }
}

Batch response

Batch response fields
FieldDescription
samplingEither directions with input-order, or horizon with its profile and altitude-then-azimuth ordering.
sampleCountNumber of direction results returned.
resultsArray of alt, az, sqm, bortleClass and bortleDescription values.
dataset / model / fallback / zenithReference / usageShared APEX provenance and accounting fields described above.
JSON Ā· batch response
{
  "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"}
  ]
}

History response

History response fields
FieldDescription
rangeInclusive from and to months actually returned.
correctionCurrent 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 entrymonth, status, dataset, baseSqm, corrected sqm, Bortle class/description and quality.
unavailable entrymonth, status, nullable dataset and reason. No other month is substituted.
usageA successful history response is charged as one zenith request, not per returned month.
JSON Ā· monthly history response
{
  "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"
    }
  ]
}

SkyTrack response overview

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.

SkyTrack response overview
FieldDescription
schema / timelineskytrack.v1 contract and one shared chronological UTC timeline with local time, UTC offset and geometric solar state.
targets / samplesFixed-target identity and J2000 coordinates, visibility intervals and physical events; samples retain time_index, geometry and eligibility.
environmentEligible samples include native modeled SQM, darkness index, airmass, extinction, low-altitude caution and background ratio.
summaryPer-target qualifying visible-dark duration, peak altitude and time, background minimum/maximum and brightness ratio, darkest positions/windows, and optional highest-efficiency windows.
impactWhen impact_analysis.enabled=true, eligible samples include conditional efficiency, fixed-time relative SNR and integration-time factor; these are normalized within each target.
provenance / usageAnnual 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.

APEX technical details

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

Access is configured for each project

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.

60-day Pro trial

New developers can activate a 60-day free Pro trial from their dashboard, with no credit card required.

The trial includes:

  • 250,000 Zenith API requests per month
  • 5,000 APEX work units per month (one directional sample uses one work unit)

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.

Pro API error response status and code reference
FieldDescription
400 Ā· INVALID_PARAMETERSInvalid coordinates, angles, month or request shape.
401 Ā· INVALID_API_KEYThe x-api-key is missing or not valid.
403 Ā· PRO_REQUIRED / API_ACCESS_DENIEDThe key lacks the required Pro access or project access is denied.
404 Ā· DATA_UNAVAILABLENo usable data is available for the requested coverage.
409 Ā· IDEMPOTENCY_CONFLICT / REQUEST_IN_PROGRESSAn idempotency key conflicts with a prior request or an identical request is still running.
413 Ā· PAYLOAD_TOO_LARGEA request or receipt exceeds a configured bound.
415 Ā· UNSUPPORTED_MEDIA_TYPEThe request body media type is not supported.
422 Ā· UNSUPPORTED_COVERAGEThe requested location is outside the supported raster coverage.
429 Ā· RATE_LIMITED / QUOTA_EXCEEDEDCapacity or the configured project allowance has been reached. Retry guidance may be returned.
500 Ā· INTERNAL_ERRORThe service encountered an unexpected internal error.
503 Ā· DATASET_STORAGE_UNAVAILABLE / CORRECTION_UNAVAILABLE / PRO_UNAVAILABLE / APEX_UNAVAILABLEStorage, corrections, Pro service or APEX is temporarily unavailable.
504 Ā· HISTORY_TIMEOUT / COMPUTE_TIMEOUTThe 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: Model the best time to observe a celestial target

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

Three targets, one observing night

Open the full SkyTrack experience →

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.

Build this into your application →

Make your first SkyTrack request

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.

cURL
# 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"
    }
  }
}'
JavaScript / Node.js
// 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
# 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.

Understanding the SkyTrack response

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.

JSON / synthetic fixture excerpt, shortened arrays
{
  "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
  }
}
Complete skytrack.v1 fixture response
JSON / complete synthetic fixture response
{
  "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
  }
}

Associate samples with timestamps

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.

JavaScript / chart-ready points
// 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.

Request configuration

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.

Endpoint contract
POST/api/sqm/skytrackPro access

Fixed-target SkyTrack timelines

Calculate 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.

Observing site

Use geographic coordinates in decimal degrees. Eligible directional evaluation requires existing native raster coverage.

Observing site
FieldDescription
site.latitude_degRequired finite number, -90 to 90 inclusive.
site.longitude_degRequired finite number, -180 to 180 inclusive.

Observing period and time zones

Choose a local civil observing night or an explicit UTC interval. Both resolve to one shared timeline, with a maximum duration of 25 hours.

Observing period and time zones
FieldDescription
period.mode = local_nightSupply 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_intervalSupply 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 zoneInferred 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.

Catalogue and manual J2000 targets

Track fixed deep-sky objects. Returned targets retain input order; moving Solar System targets are not supported.

Catalogue and manual J2000 targets
FieldDescription
targetsRequired array of 1 to 8 targets. Each client_id must be unique after trimming.
targets[].client_idRequired string, 1 to 80 characters after trimming. Use it to match returned targets to your application.
targets[].catalog_idCatalogue identifier, 1 to 100 characters after trimming. OpenNGC aliases are accepted. Unknown or ambiguous identifiers, including M102, require explicit coordinates.
targets[].coordinatesSupply 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.

Sampling and computational limits

The service rejects excessive work rather than silently coarsening your requested sampling.

Sampling and computational limits
FieldDescription
sampling.step_secondsInteger, default 600, minimum 120, maximum 90000 seconds. Both period boundaries are included.
Timeline / directionsAt most 200 shared timestamps and 1,000 eligible directions across all targets. Existing operator-configured batch caps can reduce the eligible-direction ceiling.
Body / headersContent-Type: application/json. At most 96 KiB after decompression. Authenticate with x-api-key; never put keys in URLs.
Idempotency-KeyOptional, 1 to 128 printable non-space ASCII characters. Reuse the same key and unchanged payload when retrying one logical operation.

Optional imaging-impact analysis

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.

Optional imaging-impact analysis
FieldDescription
impact_analysis.enabledBoolean. 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_minutesArray 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_skyDefaults 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.
Additional examples: multiple targets and manual J2000 coordinates

Use this full request body with the same endpoint and authentication as the Quick Start.

JSON / local night, catalogue and manual targets
{
  "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:

JSON / alternative period object
{
  "mode": "utc_interval",
  "start_utc": "2026-10-21T18:00:00Z",
  "end_utc": "2026-10-22T04:00:00Z"
}

Response reference

Shared timeline and target positions

One chronological UTC axis serves every target. Join samples through time_index, not by assuming that an eligible-only array has the same indexes.

Shared timeline and target positions
FieldDescription
apiVersion / schema / requestIdpro-v1 / skytrack.v1 / stable receipt ID. Attribution is darkskysites.com.
site / periodInput 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[].identityCanonical 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_indexZero-based index into timeline[]. Every timestamp is retained for each target, including ineligible samples.

Visibility and eligibility

Geometry remains useful even when the Sun or target position makes a directional sky-brightness sample ineligible.

Visibility and eligibility
FieldDescription
targets[].visibility_intervals / eventsExact qualifying visible-dark intervals and physical rise/set/dusk/dawn events. Clipped interval edges are labelled request_boundary, not invented physical events.
samples[].geometryaltitude_deg and azimuth_deg in degrees; above_horizon and astronomical_darkness booleans.
samples[].eligible / ineligibility_reasonEligible requires geometric target altitude >0 degrees and Sun altitude <=-18 degrees. Otherwise environment and impact are null, with an ineligibility_reason.
summary.geometryqualifying_duration_seconds; peak_altitude with altitude_deg and utc; reason when applicable.

Directional sky brightness and atmospheric extinction

Only eligible samples receive native directional photometry. No client-supplied SQM or display-RGB inference is used.

Directional sky brightness and atmospheric extinction
FieldDescription
samples[].environmentvalid and reason; sqm_mag_arcsec2 in mag/arcsec² and the existing darkness_index. Higher SQM means a darker modeled sky.
environment.airmass / extinctionairmass 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_darkestDimensionless sky-background ratio relative to this target's darkest valid sampled background. A value above 1 means brighter, not darker.
summary.sky_backgroundvalid_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.

Imaging impact and observing windows

Impact is optional and normalized within each target. It does not provide an absolute cross-target signal-to-noise ranking.

Imaging impact and observing windows
FieldDescription
samples[].impactWhen 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_impactmodel, normalization, best position and windows for requested 30/60/120-minute durations. Null when impact analysis is disabled.
Window recordsEach 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 comparisonCompare 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.

Dataset provenance

Keep the returned provenance with exported or cached results so the model and its limitations remain identifiable.

Dataset provenance
FieldDescription
provenance.model / effective_voxel_resolutionActual native solver profile and voxel resolution, not the public browser renderer profile.
dataset / fallback / zenith_referenceEnabled annual source dataset, disclosed source fallback and authoritative zenith reference. These belong within provenance.
source_key / native_identities / source_completenessNative 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_correctionsExisting native APEX SQM calibration, raw directional readback before public display rounding, and correction state.
extinction / impact_model / impact_assumptionsExtinction coefficient/formula, conditional analysis model and its assumptions.
interpolation / exclusionsInterpolation policy, annual_model, unsupported artificial_light_separation and exclusions. browser_native_parity is not asserted; browser and native solver profiles can differ.

Usage accounting

Read the actual returned receipt, not an assumed trial or project allowance.

Usage accounting
FieldDescription
usageresource: apex_work_units; charged; actual remaining headroom and resetAt. Null balances or reset times mean they are not provided, not zero allowance.
computationeligible_directions and field_batches. Eligible native directions are evaluated in one complete batch; geometry-only requests have no native field batch.

How SkyTrack estimates observing efficiency

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.

Scientific methodology
Equations / within-target normalization
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/airmass

m 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.

Limits, billing and error handling

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.

SkyTrack error codes and developer actions
Status / codeMeaningDeveloper action
400 Ā· INVALID_PARAMETERSInvalid body, target, interval, frame or idempotency key.Correct the request before retrying.
401 Ā· INVALID_API_KEYMissing or invalid x-api-key.Check the server-side credential.
403 Ā· PRO_REQUIREDThe key lacks active Pro access.Check the account's Pro entitlement.
404 Ā· DATA_UNAVAILABLENo usable source data.Check coverage/data availability; do not plot invented values.
409 Ā· IDEMPOTENCY_CONFLICTThe key was used with a different payload or operation.Use a new key only for a different logical operation.
409 Ā· REQUEST_IN_PROGRESSThe same logical request is still running.Wait, then retry the same payload and idempotency key.
413 Ā· PAYLOAD_TOO_LARGEBody or receipt exceeds an applicable bound.Reduce the request size or work requested.
415 Ā· UNSUPPORTED_MEDIA_TYPEUnsupported request media type.Send application/json.
422 Ā· UNSUPPORTED_COVERAGEThe site is outside supported raster coverage.Use a supported site; do not repeatedly retry unchanged.
429 Ā· RATE_LIMITED / QUOTA_EXCEEDEDCapacity, rate/concurrency or saved allowance reached.Follow retry guidance; check allowance/reset before retrying quota errors.
503 Ā· PRO_UNAVAILABLE / APEX_UNAVAILABLEPro admission or native computation is unavailable.Respect retryable and retry guidance; keep the logical operation's key.
504 Ā· COMPUTE_TIMEOUTThe computation deadline or connection was exceeded.Use bounded retries according to the returned guidance.