Data connectors#
- class space_pv_connectors.ArxivConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
One explicit paper per request; reuse cache and observe arXiv rate limits.
The original Atom bytes are cached with SHA-256, URL and retrieval time. This connector does not extract or promote scientific claims from PDFs. Downloading an accessible paper does not grant redistribution rights.
- class space_pv_connectors.BirdsEPSConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Connector for the public BIRDS on-orbit EPS dataset.
- download(satellite, destination)[source]#
Download one satellite workbook from the upstream BIRDS repository.
- Parameters:
- Return type:
- download_frame(satellite, destination, *, normalized=True, campaign_year=None)[source]#
Download and load a BIRDS EPS workbook.
campaign_yearsupplies the year only for campaign sheet names that omit it; seeload_birds_eps_workbook()for the time convention.
- class space_pv_connectors.DataverseConnector(*, base_url='https://darus.uni-stuttgart.de', timeout_s=30.0)[source]#
Public Dataverse search and versioned dataset access; defaults to DaRUS.
Another public installation can be selected with
base_url. Dataset and file licenses are provider-specific. Private/restricted data are not fetched.- search(query, *, start=0, page_size=25, cache_path=None, refresh=False)[source]#
Search public datasets; start is a zero-based record offset.
- dataset(persistent_id, *, version=':latest-published', cache_path=None, refresh=False)[source]#
Fetch published dataset metadata; pin
version='1.0'for reproducibility.
- class space_pv_connectors.DiscosConnector(*, token, timeout_s=30.0)[source]#
ESA DISCOS v2 metadata; free registration and an explicit token required.
DISCOS IDs and NORAD catalog numbers are different identifiers. This API supplies object/launch metadata, not ephemerides or universal PV ratings.
- objects(*, filter_expression=None, page=1, page_size=100, cache_path=None, refresh=False)[source]#
Get one page of objects using the provider’s filter syntax.
- class space_pv_connectors.DonkiConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
NASA CCMC DONKI event catalog, accessed directly without a NASA API key.
Uses the September 2026 CCMC endpoint, not the retired kauai host. Events are research context, not spacecraft-specific dose or causation evidence. Follow CCMC’s attribution and publication rules for event studies.
- class space_pv_connectors.DownloadReceipt(source: 'str', url: 'str', retrieved_at: 'str', sha256: 'str', bytes: 'int', path: 'str | None' = None)[source]#
- class space_pv_connectors.FlyingLaptopConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Retrieve CC BY 4.0 Flying Laptop monthly archives from DaRUS.
The archive contains many housekeeping packets. The normalizer reads only packet 4900, whose calibrated array currents and voltages have documented units of A and V. Downloads retain a checksum-bearing provenance sidecar.
- class space_pv_connectors.GHSLSettlementConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Retrieve JRC GHS-SMOD context while preserving its edition and epoch.
The official R2023A V2.0 global ZIP is downloaded once and reused; the 2015 archive is about 29 MB. Only a bounded native-resolution window is read into memory. The ZIP size is capped before and during downloading, and its member is validated before Rasterio opens it.
Original R2019A downloads are no longer served at the official URL as of October 2026. Use
edition='R2019A', source_path=...with a retained native historical GeoTIFF. No fallback to a different edition occurs.- fetch_settlement(*, bbox, cache_path, source_cache_dir=None, source_path=None, edition='R2023A', epoch=2015, refresh=False, offline=False, max_download_bytes=67108864, max_pixels=1000000)[source]#
Return a native crop for WGS84
(west, south, east, north).offlinepermits an existing validated crop or local source, and prevents HTTP calls.refreshreplaces a crop from the same source; archived versioned source files remain cached. A localsource_pathis hashed and its edition/epoch are caller declarations recorded in provenance; filenames alone cannot verify those declarations.
- class space_pv_connectors.GroundImage(data, crs, transform, bounds, scene_id, asset_key, source_url, asset_metadata, bbox_wgs84, item_metadata, nodata_values, retrieved_at)[source]#
A native-resolution rectangular crop, retaining raw pixel semantics.
datahas shape(bands, rows, columns); True mask entries mean missing data.transformholds affine(a, b, c, d, e, f)coefficients andboundsis(left, bottom, right, top)incrs. Pixel-aligned bounds can extend slightly beyond the requestedbbox_wgs84.visualis a rendered RGB product, not calibrated reflectance.sclis a categorical scene-classification product, not a power or irradiance measurement. No cloud masking is applied implicitly.- Parameters:
- reflectance()[source]#
Return
raw * scale + offsetusing explicit STAC band metadata.Only assets declaring the
reflectancerole are accepted. Missing data remain masked before calibration; negative reflectance values are retained. The rawdatais never modified. For example, Collection 1 commonly declares scale 0.0001 and offset -0.1, so dividing every product by 10000 without its offset would be wrong.- Return type:
- save_geotiff(destination, *, overwrite=False)[source]#
Save raw pixels, georeferencing, calibration and provenance.
The
.meta.jsonsidecar includes the complete source STAC item, asset metadata, requested/actual bounds and the output SHA-256. The checksum identifies this derived crop, not the original full tile. A GeoTIFF internal mask is used when all band masks agree. Distinct band masks are retained through a shared nodata value when possible; unsupported mask combinations raise rather than discard information.- Parameters:
- Return type:
- class space_pv_connectors.HorizonsConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Public NASA/JPL ephemerides for supported targets, including spacecraft.
Returns the original JSON envelope containing the ephemeris text, headers, units and API signature. Vectors use ICRF axes, TDB time, geometric (no light-time) corrections and AU/day units. No spacecraft attitude or PV output is implied. Target coverage is determined by JPL.
- vectors(target, *, start, stop, step='1 d', center='500@10', cache_path=None, refresh=False)[source]#
Retrieve geometric vectors; default center is the Sun’s center.
Dates are YYYY-MM-DD in TDB, with both endpoints requested. The provider may omit the final instant if the step does not land on it. Negative spacecraft IDs (e.g.
'-61'for Juno) avoid ambiguous name matches.
- class space_pv_connectors.LisirdConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Retrieve bounded, measured TSIS-1/SORCE irradiance datasets.
The LaTiS
jsondresponse carries parameter order and units. Cache files contain the original JSON bytes plus a.meta.jsonsidecar binding the response to its dataset, time range and SHA-256. Reusing a different query with the same cache path raises an error instead of returning stale data. Data access is public; retain LASP/instrument-team attribution and consult the product release notes for the version used.- total_solar_irradiance(dataset_id='tsis_tsi_24hr', *, time_min, time_max, cache_path=None)[source]#
Return measured daily or six-hourly TSI in W/m².
The interval is
[time_min, time_max)in UTC, applied to the nominal averaging-bin timestamp. At-1-AU and actual-Earth-distance irradiances remain separate. Source zero fill values become NaN; missing intervals are not interpolated.valid_measurementrequires both irradiances to be finite and positive.provisional_flagis preserved when present and is not interpreted as a missing-value flag.
- spectral_irradiance(dataset_id='tsis_ssi_24hr', *, time_min, time_max, cache_path=None)[source]#
Return measured TSIS-1 SIM spectra as wavelength-resolved rows.
Wavelength is in nm, irradiance in W/m²/nm, and the time interval is end-exclusive. All source quality bits are retained as
quality_flag;quality_goodconservatively selects zero-flag bins. Flagged bins remain in the frame. Do not integrate across missing or rejected spectral intervals or assume this 200–2400 nm product covers all TSI. At most 31 days may be requested per call to bound response size.
- class space_pv_connectors.N2YOConnector(*, api_key=None, timeout_s=30)[source]#
N2YO REST v1. Keep API keys on the server, outside browser bundles.
Positions are provider predictions, not satellite GPS telemetry. The free service documents 1,000 position calls/hour and at most 300 samples/call. No retries are made here. Bulk tracking should use cached GP + local SGP4. https://www.n2yo.com/api/
- class space_pv_connectors.NaifKernelConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Download explicitly selected NASA NAIF SPICE kernels with provenance receipt.
- class space_pv_connectors.NoaaSwpcConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
NOAA Space Weather Prediction Center JSON feed connector.
- solar_wind_magnetic_field()[source]#
Return native real-time solar-wind magnetic-field records (L1).
Preserve provider coordinates, spacecraft identity and quality fields. This is upstream solar-wind context, not a local spacecraft field model.
- Return type:
- solar_activity(product, *, cache_path=None, refresh=False)[source]#
Return UTC X-ray, Kp or alert records with source provenance.
Products are
xrays(primary GOES, rolling six hours),kp(estimated planetary Kp), andalerts(provider bulletin text). Original fields are retained. A cache is a frozen snapshot until explicitly refreshed; inspect timestamp/retrieved_at for freshness. X-rays are band-limited irradiance, not total sunlight or PV power.
- goes_integral_particle_flux(particle, *, role='primary', period='7-day', cache_path=None, refresh=False)[source]#
Fetch measured GOES integral proton or electron flux.
periodselects a rolling6-hour,1-day,3-dayor7-dayobservation feed. This is not a historical-date API.roleis primary or secondary; the actual GOES number is retained for each record.A cache stores the original response with a JSON provenance sidecar. Subsequent calls reuse that exact snapshot unless
refresh=True. A mismatched request or checksum raises instead of silently using data for another channel. Electron flux can be contaminated during energetic proton events; this feed does not supply a per-record contamination flag.
- class space_pv_connectors.NtrsConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
NASA Technical Reports Server: public metadata and available documents.
No account is needed. A search hit can be metadata-only. Preserve each record’s copyright/distribution fields; public access is not a blanket license to redistribute every paper. Design goals in papers are not flight performance measurements.
- search(query, *, offset=0, page_size=25, cache_path=None, refresh=False)[source]#
Search one page;
offsetis the zero-based record offset.
- class space_pv_connectors.OpenStreetMapEnergyConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Retrieve small-area raw solar/wind features with original OSM structure.
generator:sourceandplant:sourceselect the paper’s input features without requiring a secondpowertag. For older tagging, the query also includespower_sourceonpower=generatororpower=plantobjects. This additional legacy selection is explicit and is not an exact replay of the paper’s 2020 search.solarcan include solar thermal: inspect the source’s method/type tags before treating features as photovoltaic arrays.The result is Overpass JSON, not GeoJSON. Nodes, way-node references, all tags, relation member roles and available geometry are preserved. The query requests full geometry rather than clipping outlines at the bounding box. A way/relation can therefore extend beyond the requested region. Nested relation references remain references and may need additional resolution. No polygon merging, geometry repair, capacity parsing or clustering occurs.
The current snapshot and source timestamp are retained. The optional cache stores original response bytes and a
.meta.jsonsidecar containing the query, retrieval time, license and SHA-256. Public Overpass availability and rate limits apply; global extraction belongs in a regional/planet workflow.- fetch_energy_features(*, bbox, sources=('solar', 'wind'), cache_path=None, refresh=False)[source]#
Return the raw source-tagged nodes, ways and relations for a region.
- Parameters:
bbox (sequence of float) –
(west, south, east, north)in WGS84 longitude/latitude degrees. At most one square degree is allowed. Antimeridian-crossing regions must be split into separate boxes. This is a feature-selection box, not an exact polygon-intersection test or an output-geometry clip.sources (sequence of str) – Any nonempty subset of
("solar", "wind"). Input order and duplicate values do not change the query or cache identity.cache_path (str or pathlib.Path, optional) – Original Overpass JSON cache. An existing cache must match both the complete query and its recorded checksum; mismatches raise errors.
refresh (bool) – Fetch a new snapshot and replace the cache only after a valid, complete response has been received. Defaults to offline cache reuse.
- Returns:
Original decoded Overpass object, including
elementsand source metadata such asosm3s.timestamp_osm_basewhen provided. An empty elements list is a valid result; provider errors are never converted into an empty dataset.- Return type:
- class space_pv_connectors.OpsSatADConnector(*, timeout_s=120.0)[source]#
Download the original telemetry CSV from the fixed OPSSAT-AD v2 release.
Data are CC BY 4.0, DOI
10.5281/zenodo.15108715. The 19 MB CSV contains measured magnetometer and photodiode channels, rather than the separate handcrafted-feature table. No credentials are required.The source does not include engineering-unit declarations. Values are preserved in their published scale, without interpreting photodiodes as solar-panel current, irradiance, or generated electrical power.
- Parameters:
timeout_s (float)
- download(destination)[source]#
Download, verify, and preserve the source CSV and a provenance sidecar.
- Parameters:
- Return type:
- download_frame(destination, *, channels=None, split=None, refresh=False)[source]#
Load selected channels/split, reusing only checksum-verified cached data.
channelsis a sequence of source IDs, such as["CADC0892"].splitis"train","test", orNonefor both. Filtering keeps the source segment identifiers and the published benchmark split. A corrupt or different local file raises instead of silently replacing it.
- class space_pv_connectors.PVSite(name, bbox_wgs84, scenes, item, images, osm)[source]#
Source imagery and mapped solar features for one inspection area.
imagescontains native-gridGroundImageobjects keyed by STAC asset name.itemis the selected scene from the boundedscenessearch, andosmis the original Overpass response. Each image keeps its own resolution, mask and calibration; the map and image dates can differ.The name is a display label, not a verified inventory record. Solar-tagged OSM features still need method-tag inspection before identifying them as photovoltaic. Neither this object nor its loader infers plant boundaries, panel area, capacity, generation or completeness of OSM mapping.
- Parameters:
- class space_pv_connectors.PdsConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
NASA PDS Search API: mission product metadata, labels and data links.
Archive coverage is incomplete. Retain labels to interpret product units and calibration; a search hit is not necessarily a power measurement.
- search(query, *, limit=25, sort=None, search_after=None, cache_path=None, refresh=False)[source]#
Search using PDS
qexpressions; cursor pagination requires sort.Example:
'(product_class eq "Product_Bundle")'. Use provider field names and operators, not SQL. The documented keywords parameter is not exposed: it was silently ignored by the live service in the access check.
- class space_pv_connectors.PsaConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
ESA Planetary Science Archive TAP/EPN-TAP read-only ADQL queries.
JSON responses retain column names, units, types and data access links.
max_recordsbounds a response; reaching it may indicate truncation. The service does not provide universal spacecraft EPS telemetry.
- class space_pv_connectors.ResearchResponse(data, receipt, request_url, documentation)[source]#
Provider metadata and the receipt for its original response bytes.
request_urlincludes non-secret query parameters; authentication headers are never serialized. JSON connectors retain provider units, licenses, pagination, versions and uncertainty fields. The arXiv connector documents its Atom-to-metadata normalization and can cache original XML bytes. Neither representation is a validated engineering or PV specification.- Parameters:
data (Any)
receipt (DownloadReceipt)
request_url (str)
documentation (str)
- class space_pv_connectors.SatnogsDbConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
SatNOGS DB metadata and TLE API; telemetry endpoints require authentication.
Public satellite metadata does not imply anonymous telemetry access. The current telemetry endpoint returns HTTP 401 without credentials.
- class space_pv_connectors.Sentinel2GroundConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Search Sentinel-2 Collection 1 and retrieve ground-image assets.
Search needs only the base installation. Windowed reading needs the optional
groundextra (Rasterio). STAC item metadata stays intact, including each asset’s native resolution, calibration and nodata values. The provider’s scene-wide cloud percentage is not an AOI cloud mask.- search(*, bbox, time_min, time_max, max_cloud_cover=20.0, max_items=20, cache_path=None, refresh=False)[source]#
Return a bounded STAC FeatureCollection, clearest scenes first.
bboxis west/south/east/north in WGS84 degrees. Time bounds are inclusive UTC instants, as in STAC; a date alone means midnight.max_itemscaps unique items, not pages.context.limit_reachedflags a filled cap: this result must not be assumed exhaustive.POST/GET pagination is followed with its declared body/merge semantics. Cached snapshots preserve full item metadata and a SHA-256 sidecar binding the file to this query. A changed query or damaged snapshot raises an error;
refresh=Trueexplicitly replaces the snapshot.
- static read_image(item, *, bbox, asset='visual', max_pixels=4000000)[source]#
Read a native-resolution COG window; see
read_ground_image().
- download_asset(item, asset, destination, *, max_bytes=1000000000, overwrite=False)[source]#
Stream a complete asset to disk with a checksum/provenance sidecar.
Full Sentinel-2 bands can be hundreds of MB. Prefer
read_imagefor farm-sized areas. The size ceiling is enforced while streaming, and a failed request never replaces an existing destination.
- class space_pv_connectors.SettlementRaster(data, crs, transform, bounds, bbox_wgs84, epoch, edition, provenance)[source]#
A native 1 km categorical GHSL crop and its source provenance.
datais a two-dimensional masked integer array. These classes describe settlement context atepoch; they do not describe current PV land use or validate an individual rooftop, ground-mounted plant or water boundary. The original grid is retained, unlike the paper’s Eckert IV reprojection.- Parameters:
- sample_points(lon_lat)[source]#
Sample WGS84 points without interpolation; unknown flags are None.
Supplying farm centroids implements a clearly defined centroid lookup. It does not calculate the fraction of an entire farm covered by water or urban cells. Outside-crop, masked and unknown-code results remain explicit rather than being counted as rural/non-water observations.
- class space_pv_connectors.SpaceTrackConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Authenticated Space-Track GP/GP-history connector.
Credentials should be supplied by environment/secrets management, never committed.
- latest_gp_cached(norad_cat_id, *, cache_path)[source]#
Reuse current OMM for two hours; authenticate first on a cache miss.
Shares the same persistent snapshot/provenance contract as CelesTrak. This conservative interval also satisfies Space-Track’s hourly GP limit.
- Parameters:
- Return type:
- gp_history(norad_cat_id, *, start, end, cache_dir, max_records=100000)[source]#
Fetch and cache a bounded, complete EPOCH interval in chronological order.
Space-Track requests that GP history be downloaded once and reused from disk. A mandatory cache prevents repeated calls for an identical interval.
startandendare inclusive, timezone-aware element epochs, not publication dates. Authentication is required for a cache miss. Queries over one year should use provider bulk/year files instead.
- class space_pv_connectors.SscWebConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
NASA Satellite Situation Center metadata and ephemeris-service connector.
- class space_pv_connectors.ZenodoConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Discover published research datasets and download open files anonymously.
Restricted files remain restricted. Each record supplies its own license; no deposit, publication or authenticated write endpoints are used.
- search(query, *, page=1, page_size=25, cache_path=None, refresh=False)[source]#
Search one page using Zenodo query syntax (anonymous maximum: 25).
- space_pv_connectors.load_birds_eps_workbook(path, *, normalized=True, campaign_year=None)[source]#
Load a downloaded BIRDS EPS workbook into the canonical panel schema.
- Parameters:
path (str or pathlib.Path) – Downloaded upstream XLSX workbook.
normalized (bool, default True) – Return panel-level flight telemetry. The known undated TSURU sheets
Test1 w battandTest2 wo battare excluded from this mode.Falsereturns raw rows from every nonempty sheet, including tests.campaign_year (int, optional) – Explicit year for campaign sheet dates that omit it. For example, the TSURU 2021 flight campaigns require
campaign_year=2021. A year already stated in a sheet name is always preserved. No current-year assumption is made; an omitted year raises an actionable error.
- Return type:
Notes
Calibrated numeric
Time Stampvalues are elapsed seconds. The returnedtimestampanchors these to midnight oncampaign_datefor ordering; this is not a known absolute UTC acquisition time. The original clock is retained inelapsed_secondsand the convention intimestamp_basis.campaign_date_basisrecords whether a year was supplied by the caller. Rows without a valid elapsed clock or voltage/current pair are omitted.
- space_pv_connectors.load_flying_laptop_power(path, *, time_min=None, time_max=None)[source]#
Read calibrated solar-array V, I and computed power from a local archive.
time_minis inclusive andtime_maxexclusive; naive bounds are UTC. Timestamps are the source’s Unix epoch milliseconds in UTC, identifying packet generation. The source documents up to 400 ms of additional sensor acquisition delay. Missing/invalid readings remain missing and are omitted per voltage/current pair; signed sensor values are not clipped.Four panel identifiers are preserved:
right,left,centerandtest. Heretestis the spacecraft’s experimental array channel, not a separate ground-test recording. Power is computed as V times I; no independently transmitted power measurement is implied.The reader streams only matching packet 4900 members, never extracting archive paths to disk. A downloaded provenance sidecar, when present, is verified against the local archive. Source metadata is returned in attrs.
- space_pv_connectors.load_goes_integral_particle_flux(path, *, particle)[source]#
Read an original SWPC integral-flux JSON snapshot without network access.
Raw fields are retained. Negative, nonfinite or missing flux values become NaN in
flux_cm2_s_srand are flagged byis_valid_flux. Integral energy channels overlap and must not be added together. Satellite identity is taken from every measurement, since primary proton/electron sources can differ.
- space_pv_connectors.load_ground_image(path, *, max_pixels=4000000)[source]#
Load a saved native crop after verifying its pixels and provenance.
Read the GeoTIFF and
.meta.jsonwritten byGroundImage.save_geotiff(). The SHA-256, byte count, source identity, native grid, nodata and calibration must agree. The metadata’s originalpathis informational, so snapshots can move between computers. Unverified external mask/PAM files are rejected.max_pixelscounts all band samples and is enforced before reading the pixels. Raw values, per-band masks and the complete source STAC item are retained; this function never makes network requests or applies calibration.- Parameters:
- Return type:
- space_pv_connectors.load_opssat_segments(path, *, channels=None, split=None)[source]#
Read original OPSSAT-AD telemetry without resampling or merging segments.
Every source column is retained.
timestampbecomes a UTC datetime;valuestays on its original published scale. Missing/nonfinite values are retained and marked byis_valid_value; no fill value or physical unit is invented.value_unitexplicitly records that units are absent from the source CSV.Use the source’s numeric
anomalyfield for the expert annotation. The textuallabelcolumn contains"anomaly"even for nominal segments in v2, so it must not be treated as a classification result.trainis the fixed benchmark split, not a chronological split.A local subset may be loaded for offline analysis. The returned
attrscontain its checksum and whether it matches the complete pinned release.
- space_pv_connectors.load_pv_site(*, bbox, time_min, time_max, cache_dir, name='PV site', cache_prefix='site', max_cloud_cover=20.0, max_items=10, scene_id=None, assets=('visual', 'red', 'scl'), offline=False, refresh=False, timeout_s=60.0, max_pixels=4000000)[source]#
Load or retrieve imagery and OSM inputs for a small PV inspection area.
Search Sentinel-2 Collection 1, select the first (lowest scene-cloud-cover) returned item by default, load native crops, and retrieve raw solar-tagged OSM features. A supplied
scene_idmust occur in the bounded search. Search intersection does not guarantee full raster coverage; the underlying crop reader raises for tile-edge areas rather than mosaicking implicitly.bboxis WGS84(west, south, east, north)and must satisfy the OSM connector’s one-square-degree limit. Time bounds are inclusive UTC instants. Scene-wide cloud cover is not a local cloud mask. Inspect quality classes andsite.scenes['context']['limit_reached']when selecting inputs.The cache contains
{prefix}-scenes.json,{prefix}-osm.jsonand{prefix}-{asset}.tif, each with its provenance sidecar. Existing caches must match the request, SHA-256, selected scene, asset metadata and grid. Only missing files are retrieved; incomplete or inconsistent caches raise.refresh=Trueexplicitly retrieves replacement snapshots and crops. A refresh is not a transaction across all files: if it fails, retry with refresh enabled or use a new cache prefix. Mixed snapshots fail validation.offline=Truerequires every source file and sidecar before any loading begins, blocks HTTP fallback, and cannot be combined withrefresh=True.max_pixelslimits band samples per asset, not the sum across assets. Installorbital-pv[ground]for GeoTIFF support; plotting is separate.
- space_pv_connectors.load_settlement_raster(path, *, max_pixels=1000000)[source]#
Restore and verify a saved GHSL crop entirely offline.
- Parameters:
- Return type:
- space_pv_connectors.parse_arxiv_atom(content, paper_id)[source]#
Parse one exact-version Atom entry; never silently substitute latest.
- space_pv_connectors.read_ground_image(item, *, bbox, asset='visual', max_pixels=4000000)[source]#
Read a WGS84 area from one HTTPS GeoTIFF asset at native resolution.
bboxis(west, south, east, north)in longitude/latitude degrees. The crop covers the transformed bounding rectangle, rounded outward to source pixels; it is not an exact polygon clip. The selected tile must cover the entire crop. Select another tile or mosaic explicitly when an area crosses a tile edge.max_pixelslimits the total band samples (bands * rows * columns) before pixel data are read. COG range reads retrieve the intersecting compressed blocks, which can be larger than the requested pixel window. Different assets retain their native grids (e.g. RGB 10 m, SCL 20 m). No reprojection, resampling, reflectance scaling or cloud mask occurs.
Ground satellite imagery#
Ground imagery from the public Earth Search Sentinel-2 STAC API.
The default Collection 1 product supplies native-resolution COG assets without an account. Imagery supports inspection of terrestrial energy installations; it is not an estimate of generated power or a reproduction of Dunnett (2020). Source: Element84/earth-search.
- class space_pv_connectors.ground_imagery.Sentinel2GroundConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Search Sentinel-2 Collection 1 and retrieve ground-image assets.
Search needs only the base installation. Windowed reading needs the optional
groundextra (Rasterio). STAC item metadata stays intact, including each asset’s native resolution, calibration and nodata values. The provider’s scene-wide cloud percentage is not an AOI cloud mask.- search(*, bbox, time_min, time_max, max_cloud_cover=20.0, max_items=20, cache_path=None, refresh=False)[source]#
Return a bounded STAC FeatureCollection, clearest scenes first.
bboxis west/south/east/north in WGS84 degrees. Time bounds are inclusive UTC instants, as in STAC; a date alone means midnight.max_itemscaps unique items, not pages.context.limit_reachedflags a filled cap: this result must not be assumed exhaustive.POST/GET pagination is followed with its declared body/merge semantics. Cached snapshots preserve full item metadata and a SHA-256 sidecar binding the file to this query. A changed query or damaged snapshot raises an error;
refresh=Trueexplicitly replaces the snapshot.
- static read_image(item, *, bbox, asset='visual', max_pixels=4000000)[source]#
Read a native-resolution COG window; see
read_ground_image().
- download_asset(item, asset, destination, *, max_bytes=1000000000, overwrite=False)[source]#
Stream a complete asset to disk with a checksum/provenance sidecar.
Full Sentinel-2 bands can be hundreds of MB. Prefer
read_imagefor farm-sized areas. The size ceiling is enforced while streaming, and a failed request never replaces an existing destination.
Native-grid subsets of public ground-imaging Cloud Optimized GeoTIFFs.
Rasterio is optional and is imported only when reading or writing an image. Pixels retain their source values, resolution and nodata mask. This module does not infer farm boundaries, resample bands or classify cloudy pixels.
- class space_pv_connectors.ground_raster.GroundImage(data, crs, transform, bounds, scene_id, asset_key, source_url, asset_metadata, bbox_wgs84, item_metadata, nodata_values, retrieved_at)[source]#
A native-resolution rectangular crop, retaining raw pixel semantics.
datahas shape(bands, rows, columns); True mask entries mean missing data.transformholds affine(a, b, c, d, e, f)coefficients andboundsis(left, bottom, right, top)incrs. Pixel-aligned bounds can extend slightly beyond the requestedbbox_wgs84.visualis a rendered RGB product, not calibrated reflectance.sclis a categorical scene-classification product, not a power or irradiance measurement. No cloud masking is applied implicitly.- Parameters:
- reflectance()[source]#
Return
raw * scale + offsetusing explicit STAC band metadata.Only assets declaring the
reflectancerole are accepted. Missing data remain masked before calibration; negative reflectance values are retained. The rawdatais never modified. For example, Collection 1 commonly declares scale 0.0001 and offset -0.1, so dividing every product by 10000 without its offset would be wrong.- Return type:
- save_geotiff(destination, *, overwrite=False)[source]#
Save raw pixels, georeferencing, calibration and provenance.
The
.meta.jsonsidecar includes the complete source STAC item, asset metadata, requested/actual bounds and the output SHA-256. The checksum identifies this derived crop, not the original full tile. A GeoTIFF internal mask is used when all band masks agree. Distinct band masks are retained through a shared nodata value when possible; unsupported mask combinations raise rather than discard information.- Parameters:
- Return type:
- space_pv_connectors.ground_raster.load_ground_image(path, *, max_pixels=4000000)[source]#
Load a saved native crop after verifying its pixels and provenance.
Read the GeoTIFF and
.meta.jsonwritten byGroundImage.save_geotiff(). The SHA-256, byte count, source identity, native grid, nodata and calibration must agree. The metadata’s originalpathis informational, so snapshots can move between computers. Unverified external mask/PAM files are rejected.max_pixelscounts all band samples and is enforced before reading the pixels. Raw values, per-band masks and the complete source STAC item are retained; this function never makes network requests or applies calibration.- Parameters:
- Return type:
- space_pv_connectors.ground_raster.read_ground_image(item, *, bbox, asset='visual', max_pixels=4000000)[source]#
Read a WGS84 area from one HTTPS GeoTIFF asset at native resolution.
bboxis(west, south, east, north)in longitude/latitude degrees. The crop covers the transformed bounding rectangle, rounded outward to source pixels; it is not an exact polygon clip. The selected tile must cover the entire crop. Select another tile or mosaic explicitly when an area crosses a tile edge.max_pixelslimits the total band samples (bands * rows * columns) before pixel data are read. COG range reads retrieve the intersecting compressed blocks, which can be larger than the requested pixel window. Different assets retain their native grids (e.g. RGB 10 m, SCL 20 m). No reprojection, resampling, reflectance scaling or cloud mask occurs.
Cached PV site inputs#
Reusable, provenance-checked inputs for inspecting terrestrial PV sites.
- class space_pv_connectors.ground_site.PVSite(name, bbox_wgs84, scenes, item, images, osm)[source]#
Source imagery and mapped solar features for one inspection area.
imagescontains native-gridGroundImageobjects keyed by STAC asset name.itemis the selected scene from the boundedscenessearch, andosmis the original Overpass response. Each image keeps its own resolution, mask and calibration; the map and image dates can differ.The name is a display label, not a verified inventory record. Solar-tagged OSM features still need method-tag inspection before identifying them as photovoltaic. Neither this object nor its loader infers plant boundaries, panel area, capacity, generation or completeness of OSM mapping.
- Parameters:
- space_pv_connectors.ground_site.load_pv_site(*, bbox, time_min, time_max, cache_dir, name='PV site', cache_prefix='site', max_cloud_cover=20.0, max_items=10, scene_id=None, assets=('visual', 'red', 'scl'), offline=False, refresh=False, timeout_s=60.0, max_pixels=4000000)[source]#
Load or retrieve imagery and OSM inputs for a small PV inspection area.
Search Sentinel-2 Collection 1, select the first (lowest scene-cloud-cover) returned item by default, load native crops, and retrieve raw solar-tagged OSM features. A supplied
scene_idmust occur in the bounded search. Search intersection does not guarantee full raster coverage; the underlying crop reader raises for tile-edge areas rather than mosaicking implicitly.bboxis WGS84(west, south, east, north)and must satisfy the OSM connector’s one-square-degree limit. Time bounds are inclusive UTC instants. Scene-wide cloud cover is not a local cloud mask. Inspect quality classes andsite.scenes['context']['limit_reached']when selecting inputs.The cache contains
{prefix}-scenes.json,{prefix}-osm.jsonand{prefix}-{asset}.tif, each with its provenance sidecar. Existing caches must match the request, SHA-256, selected scene, asset metadata and grid. Only missing files are retrieved; incomplete or inconsistent caches raise.refresh=Trueexplicitly retrieves replacement snapshots and crops. A refresh is not a transaction across all files: if it fails, retry with refresh enabled or use a new cache prefix. Mixed snapshots fail validation.offline=Truerequires every source file and sidecar before any loading begins, blocks HTTP fallback, and cannot be combined withrefresh=True.max_pixelslimits band samples per asset, not the sum across assets. Installorbital-pv[ground]for GeoTIFF support; plotting is separate.
Ground renewable-energy features#
Ground energy features from OpenStreetMap’s public Overpass API.
The primary source-tag selection follows Dunnett et al. (2020), https://doi.org/10.1038/s41597-020-0469-8. The raw extract is not a reproduction of their historical database, spatial clustering, or capacity estimates. OpenStreetMap data are © OpenStreetMap contributors, licensed under ODbL: https://www.openstreetmap.org/copyright.
- class space_pv_connectors.ground_osm.OpenStreetMapEnergyConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Retrieve small-area raw solar/wind features with original OSM structure.
generator:sourceandplant:sourceselect the paper’s input features without requiring a secondpowertag. For older tagging, the query also includespower_sourceonpower=generatororpower=plantobjects. This additional legacy selection is explicit and is not an exact replay of the paper’s 2020 search.solarcan include solar thermal: inspect the source’s method/type tags before treating features as photovoltaic arrays.The result is Overpass JSON, not GeoJSON. Nodes, way-node references, all tags, relation member roles and available geometry are preserved. The query requests full geometry rather than clipping outlines at the bounding box. A way/relation can therefore extend beyond the requested region. Nested relation references remain references and may need additional resolution. No polygon merging, geometry repair, capacity parsing or clustering occurs.
The current snapshot and source timestamp are retained. The optional cache stores original response bytes and a
.meta.jsonsidecar containing the query, retrieval time, license and SHA-256. Public Overpass availability and rate limits apply; global extraction belongs in a regional/planet workflow.- fetch_energy_features(*, bbox, sources=('solar', 'wind'), cache_path=None, refresh=False)[source]#
Return the raw source-tagged nodes, ways and relations for a region.
- Parameters:
bbox (sequence of float) –
(west, south, east, north)in WGS84 longitude/latitude degrees. At most one square degree is allowed. Antimeridian-crossing regions must be split into separate boxes. This is a feature-selection box, not an exact polygon-intersection test or an output-geometry clip.sources (sequence of str) – Any nonempty subset of
("solar", "wind"). Input order and duplicate values do not change the query or cache identity.cache_path (str or pathlib.Path, optional) – Original Overpass JSON cache. An existing cache must match both the complete query and its recorded checksum; mismatches raise errors.
refresh (bool) – Fetch a new snapshot and replace the cache only after a valid, complete response has been received. Defaults to offline cache reuse.
- Returns:
Original decoded Overpass object, including
elementsand source metadata such asosm3s.timestamp_osm_basewhen provided. An empty elements list is a valid result; provider errors are never converted into an empty dataset.- Return type:
Historical settlement context#
Native GHSL settlement classes for terrestrial PV inventory context.
The paper’s urban categories are codes 21, 22, 23 and 30; water is code 10. R2023A is a newer processing edition, even when its epoch is 2015. It is not the historical R2019A input used by Dunnett et al. (2020). A local R2019A raster can be supplied explicitly; editions are never substituted silently.
Sources: https://doi.org/10.1038/s41597-020-0469-8 and the JRC GHSL manuals, https://human-settlement.emergency.copernicus.eu/documents/GHSL_Data_Package_2019.pdf and https://human-settlement.emergency.copernicus.eu/ghs_smod2023.php.
- class space_pv_connectors.ground_ghsl.SettlementRaster(data, crs, transform, bounds, bbox_wgs84, epoch, edition, provenance)[source]#
A native 1 km categorical GHSL crop and its source provenance.
datais a two-dimensional masked integer array. These classes describe settlement context atepoch; they do not describe current PV land use or validate an individual rooftop, ground-mounted plant or water boundary. The original grid is retained, unlike the paper’s Eckert IV reprojection.- Parameters:
- sample_points(lon_lat)[source]#
Sample WGS84 points without interpolation; unknown flags are None.
Supplying farm centroids implements a clearly defined centroid lookup. It does not calculate the fraction of an entire farm covered by water or urban cells. Outside-crop, masked and unknown-code results remain explicit rather than being counted as rural/non-water observations.
- space_pv_connectors.ground_ghsl.load_settlement_raster(path, *, max_pixels=1000000)[source]#
Restore and verify a saved GHSL crop entirely offline.
- Parameters:
- Return type:
- class space_pv_connectors.ground_ghsl.GHSLSettlementConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Retrieve JRC GHS-SMOD context while preserving its edition and epoch.
The official R2023A V2.0 global ZIP is downloaded once and reused; the 2015 archive is about 29 MB. Only a bounded native-resolution window is read into memory. The ZIP size is capped before and during downloading, and its member is validated before Rasterio opens it.
Original R2019A downloads are no longer served at the official URL as of October 2026. Use
edition='R2019A', source_path=...with a retained native historical GeoTIFF. No fallback to a different edition occurs.- fetch_settlement(*, bbox, cache_path, source_cache_dir=None, source_path=None, edition='R2023A', epoch=2015, refresh=False, offline=False, max_download_bytes=67108864, max_pixels=1000000)[source]#
Return a native crop for WGS84
(west, south, east, north).offlinepermits an existing validated crop or local source, and prevents HTTP calls.refreshreplaces a crop from the same source; archived versioned source files remain cached. A localsource_pathis hashed and its edition/epoch are caller declarations recorded in provenance; filenames alone cannot verify those declarations.
BIRDS EPS#
- class space_pv_connectors.birds.BirdsEPSConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Connector for the public BIRDS on-orbit EPS dataset.
- download(satellite, destination)[source]#
Download one satellite workbook from the upstream BIRDS repository.
- Parameters:
- Return type:
- download_frame(satellite, destination, *, normalized=True, campaign_year=None)[source]#
Download and load a BIRDS EPS workbook.
campaign_yearsupplies the year only for campaign sheet names that omit it; seeload_birds_eps_workbook()for the time convention.
- space_pv_connectors.birds.load_birds_eps_workbook(path, *, normalized=True, campaign_year=None)[source]#
Load a downloaded BIRDS EPS workbook into the canonical panel schema.
- Parameters:
path (str or pathlib.Path) – Downloaded upstream XLSX workbook.
normalized (bool, default True) – Return panel-level flight telemetry. The known undated TSURU sheets
Test1 w battandTest2 wo battare excluded from this mode.Falsereturns raw rows from every nonempty sheet, including tests.campaign_year (int, optional) – Explicit year for campaign sheet dates that omit it. For example, the TSURU 2021 flight campaigns require
campaign_year=2021. A year already stated in a sheet name is always preserved. No current-year assumption is made; an omitted year raises an actionable error.
- Return type:
Notes
Calibrated numeric
Time Stampvalues are elapsed seconds. The returnedtimestampanchors these to midnight oncampaign_datefor ordering; this is not a known absolute UTC acquisition time. The original clock is retained inelapsed_secondsand the convention intimestamp_basis.campaign_date_basisrecords whether a year was supplied by the caller. Rows without a valid elapsed clock or voltage/current pair are omitted.
CelesTrak#
Flying Laptop measured arrays#
Calibrated on-orbit solar-array telemetry from the Flying Laptop mission.
- class space_pv_connectors.flying_laptop.FlyingLaptopConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Retrieve CC BY 4.0 Flying Laptop monthly archives from DaRUS.
The archive contains many housekeeping packets. The normalizer reads only packet 4900, whose calibrated array currents and voltages have documented units of A and V. Downloads retain a checksum-bearing provenance sidecar.
- space_pv_connectors.flying_laptop.load_flying_laptop_power(path, *, time_min=None, time_max=None)[source]#
Read calibrated solar-array V, I and computed power from a local archive.
time_minis inclusive andtime_maxexclusive; naive bounds are UTC. Timestamps are the source’s Unix epoch milliseconds in UTC, identifying packet generation. The source documents up to 400 ms of additional sensor acquisition delay. Missing/invalid readings remain missing and are omitted per voltage/current pair; signed sensor values are not clipped.Four panel identifiers are preserved:
right,left,centerandtest. Heretestis the spacecraft’s experimental array channel, not a separate ground-test recording. Power is computed as V times I; no independently transmitted power measurement is implied.The reader streams only matching packet 4900 members, never extracting archive paths to disk. A downloaded provenance sidecar, when present, is verified against the local archive. Source metadata is returned in attrs.
OPS-SAT annotated measurements#
Original, annotated OPS-SAT telemetry segments from the pinned OPSSAT-AD v2 release.
- class space_pv_connectors.opssat.OpsSatADConnector(*, timeout_s=120.0)[source]#
Download the original telemetry CSV from the fixed OPSSAT-AD v2 release.
Data are CC BY 4.0, DOI
10.5281/zenodo.15108715. The 19 MB CSV contains measured magnetometer and photodiode channels, rather than the separate handcrafted-feature table. No credentials are required.The source does not include engineering-unit declarations. Values are preserved in their published scale, without interpreting photodiodes as solar-panel current, irradiance, or generated electrical power.
- Parameters:
timeout_s (float)
- download(destination)[source]#
Download, verify, and preserve the source CSV and a provenance sidecar.
- Parameters:
- Return type:
- download_frame(destination, *, channels=None, split=None, refresh=False)[source]#
Load selected channels/split, reusing only checksum-verified cached data.
channelsis a sequence of source IDs, such as["CADC0892"].splitis"train","test", orNonefor both. Filtering keeps the source segment identifiers and the published benchmark split. A corrupt or different local file raises instead of silently replacing it.
- space_pv_connectors.opssat.load_opssat_segments(path, *, channels=None, split=None)[source]#
Read original OPSSAT-AD telemetry without resampling or merging segments.
Every source column is retained.
timestampbecomes a UTC datetime;valuestays on its original published scale. Missing/nonfinite values are retained and marked byis_valid_value; no fill value or physical unit is invented.value_unitexplicitly records that units are absent from the source CSV.Use the source’s numeric
anomalyfield for the expert annotation. The textuallabelcolumn contains"anomaly"even for nominal segments in v2, so it must not be treated as a classification result.trainis the fixed benchmark split, not a chronological split.A local subset may be loaded for offline analysis. The returned
attrscontain its checksum and whether it matches the complete pinned release.
LASP measured irradiance#
Measured total and spectral solar irradiance from LASP LISIRD.
These calibrated Level-3 science products measure incoming sunlight; they are not solar-array electrical-output telemetry. Source: https://lasp.colorado.edu/lisird/ and https://lasp.colorado.edu/tsis/data/.
- class space_pv_connectors.lisird.LisirdConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Retrieve bounded, measured TSIS-1/SORCE irradiance datasets.
The LaTiS
jsondresponse carries parameter order and units. Cache files contain the original JSON bytes plus a.meta.jsonsidecar binding the response to its dataset, time range and SHA-256. Reusing a different query with the same cache path raises an error instead of returning stale data. Data access is public; retain LASP/instrument-team attribution and consult the product release notes for the version used.- total_solar_irradiance(dataset_id='tsis_tsi_24hr', *, time_min, time_max, cache_path=None)[source]#
Return measured daily or six-hourly TSI in W/m².
The interval is
[time_min, time_max)in UTC, applied to the nominal averaging-bin timestamp. At-1-AU and actual-Earth-distance irradiances remain separate. Source zero fill values become NaN; missing intervals are not interpolated.valid_measurementrequires both irradiances to be finite and positive.provisional_flagis preserved when present and is not interpreted as a missing-value flag.
- spectral_irradiance(dataset_id='tsis_ssi_24hr', *, time_min, time_max, cache_path=None)[source]#
Return measured TSIS-1 SIM spectra as wavelength-resolved rows.
Wavelength is in nm, irradiance in W/m²/nm, and the time interval is end-exclusive. All source quality bits are retained as
quality_flag;quality_goodconservatively selects zero-flag bins. Flagged bins remain in the frame. Do not integrate across missing or rejected spectral intervals or assume this 200–2400 nm product covers all TSI. At most 31 days may be requested per call to bound response size.
Space-Track#
- class space_pv_connectors.space_track.SpaceTrackConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Authenticated Space-Track GP/GP-history connector.
Credentials should be supplied by environment/secrets management, never committed.
- latest_gp_cached(norad_cat_id, *, cache_path)[source]#
Reuse current OMM for two hours; authenticate first on a cache miss.
Shares the same persistent snapshot/provenance contract as CelesTrak. This conservative interval also satisfies Space-Track’s hourly GP limit.
- Parameters:
- Return type:
- gp_history(norad_cat_id, *, start, end, cache_dir, max_records=100000)[source]#
Fetch and cache a bounded, complete EPOCH interval in chronological order.
Space-Track requests that GP history be downloaded once and reused from disk. A mandatory cache prevents repeated calls for an identical interval.
startandendare inclusive, timezone-aware element epochs, not publication dates. Authentication is required for a cache miss. Queries over one year should use provider bulk/year files instead.
SatNOGS#
- class space_pv_connectors.satnogs.SatnogsDbConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
SatNOGS DB metadata and TLE API; telemetry endpoints require authentication.
Public satellite metadata does not imply anonymous telemetry access. The current telemetry endpoint returns HTTP 401 without credentials.
NASA / NOAA services#
- class space_pv_connectors.sscweb.SscWebConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
NASA Satellite Situation Center metadata and ephemeris-service connector.
- class space_pv_connectors.naif.NaifKernelConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Download explicitly selected NASA NAIF SPICE kernels with provenance receipt.
- class space_pv_connectors.swpc.NoaaSwpcConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
NOAA Space Weather Prediction Center JSON feed connector.
- solar_wind_magnetic_field()[source]#
Return native real-time solar-wind magnetic-field records (L1).
Preserve provider coordinates, spacecraft identity and quality fields. This is upstream solar-wind context, not a local spacecraft field model.
- Return type:
- solar_activity(product, *, cache_path=None, refresh=False)[source]#
Return UTC X-ray, Kp or alert records with source provenance.
Products are
xrays(primary GOES, rolling six hours),kp(estimated planetary Kp), andalerts(provider bulletin text). Original fields are retained. A cache is a frozen snapshot until explicitly refreshed; inspect timestamp/retrieved_at for freshness. X-rays are band-limited irradiance, not total sunlight or PV power.
- goes_integral_particle_flux(particle, *, role='primary', period='7-day', cache_path=None, refresh=False)[source]#
Fetch measured GOES integral proton or electron flux.
periodselects a rolling6-hour,1-day,3-dayor7-dayobservation feed. This is not a historical-date API.roleis primary or secondary; the actual GOES number is retained for each record.A cache stores the original response with a JSON provenance sidecar. Subsequent calls reuse that exact snapshot unless
refresh=True. A mismatched request or checksum raises instead of silently using data for another channel. Electron flux can be contaminated during energetic proton events; this feed does not supply a per-record contamination flag.
- space_pv_connectors.swpc.load_goes_integral_particle_flux(path, *, particle)[source]#
Read an original SWPC integral-flux JSON snapshot without network access.
Raw fields are retained. Negative, nonfinite or missing flux values become NaN in
flux_cm2_s_srand are flagged byis_valid_flux. Integral energy channels overlap and must not be added together. Satellite identity is taken from every measurement, since primary proton/electron sources can differ.
- space_pv_connectors.swpc.normalize_solar_activity(payload, product)[source]#
Normalize native SWPC snapshots without network access.
Negative/nonfinite flux and Kp outside 0–9 are flagged and masked in canonical columns, while raw source fields remain available for auditing. Empty lists represent no records, never fabricated quiet conditions.
Free spacecraft research APIs#
Free spacecraft metadata, technical literature, archives and geometry APIs.
These connectors return provider facts with provenance. They do not infer PV ratings, parse technical papers into accepted catalogue records, or turn space weather events into spacecraft radiation doses. Searches return one bounded page; retain provider totals/links and request subsequent pages explicitly.
- class space_pv_connectors.research.DataverseConnector(*, base_url='https://darus.uni-stuttgart.de', timeout_s=30.0)[source]#
Public Dataverse search and versioned dataset access; defaults to DaRUS.
Another public installation can be selected with
base_url. Dataset and file licenses are provider-specific. Private/restricted data are not fetched.- search(query, *, start=0, page_size=25, cache_path=None, refresh=False)[source]#
Search public datasets; start is a zero-based record offset.
- dataset(persistent_id, *, version=':latest-published', cache_path=None, refresh=False)[source]#
Fetch published dataset metadata; pin
version='1.0'for reproducibility.
- class space_pv_connectors.research.DiscosConnector(*, token, timeout_s=30.0)[source]#
ESA DISCOS v2 metadata; free registration and an explicit token required.
DISCOS IDs and NORAD catalog numbers are different identifiers. This API supplies object/launch metadata, not ephemerides or universal PV ratings.
- objects(*, filter_expression=None, page=1, page_size=100, cache_path=None, refresh=False)[source]#
Get one page of objects using the provider’s filter syntax.
- class space_pv_connectors.research.DonkiConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
NASA CCMC DONKI event catalog, accessed directly without a NASA API key.
Uses the September 2026 CCMC endpoint, not the retired kauai host. Events are research context, not spacecraft-specific dose or causation evidence. Follow CCMC’s attribution and publication rules for event studies.
- class space_pv_connectors.research.HorizonsConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Public NASA/JPL ephemerides for supported targets, including spacecraft.
Returns the original JSON envelope containing the ephemeris text, headers, units and API signature. Vectors use ICRF axes, TDB time, geometric (no light-time) corrections and AU/day units. No spacecraft attitude or PV output is implied. Target coverage is determined by JPL.
- vectors(target, *, start, stop, step='1 d', center='500@10', cache_path=None, refresh=False)[source]#
Retrieve geometric vectors; default center is the Sun’s center.
Dates are YYYY-MM-DD in TDB, with both endpoints requested. The provider may omit the final instant if the step does not land on it. Negative spacecraft IDs (e.g.
'-61'for Juno) avoid ambiguous name matches.
- class space_pv_connectors.research.NtrsConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
NASA Technical Reports Server: public metadata and available documents.
No account is needed. A search hit can be metadata-only. Preserve each record’s copyright/distribution fields; public access is not a blanket license to redistribute every paper. Design goals in papers are not flight performance measurements.
- search(query, *, offset=0, page_size=25, cache_path=None, refresh=False)[source]#
Search one page;
offsetis the zero-based record offset.
- class space_pv_connectors.research.PdsConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
NASA PDS Search API: mission product metadata, labels and data links.
Archive coverage is incomplete. Retain labels to interpret product units and calibration; a search hit is not necessarily a power measurement.
- search(query, *, limit=25, sort=None, search_after=None, cache_path=None, refresh=False)[source]#
Search using PDS
qexpressions; cursor pagination requires sort.Example:
'(product_class eq "Product_Bundle")'. Use provider field names and operators, not SQL. The documented keywords parameter is not exposed: it was silently ignored by the live service in the access check.
- class space_pv_connectors.research.PsaConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
ESA Planetary Science Archive TAP/EPN-TAP read-only ADQL queries.
JSON responses retain column names, units, types and data access links.
max_recordsbounds a response; reaching it may indicate truncation. The service does not provide universal spacecraft EPS telemetry.
- class space_pv_connectors.research.ZenodoConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
Discover published research datasets and download open files anonymously.
Restricted files remain restricted. Each record supplies its own license; no deposit, publication or authenticated write endpoints are used.
- search(query, *, page=1, page_size=25, cache_path=None, refresh=False)[source]#
Search one page using Zenodo query syntax (anonymous maximum: 25).
Provenance and bounded downloads shared by the research API connectors.
- class space_pv_connectors.research_http.ResearchResponse(data, receipt, request_url, documentation)[source]#
Provider metadata and the receipt for its original response bytes.
request_urlincludes non-secret query parameters; authentication headers are never serialized. JSON connectors retain provider units, licenses, pagination, versions and uncertainty fields. The arXiv connector documents its Atom-to-metadata normalization and can cache original XML bytes. Neither representation is a validated engineering or PV specification.- Parameters:
data (Any)
receipt (DownloadReceipt)
request_url (str)
documentation (str)
Tabular utilities#
GP snapshot cache#
Persistent GP snapshots with a cross-process download lock and circuit breaker.
- class space_pv_connectors.gp_cache.GPSnapshot(records: 'list[dict[str, Any]]', source: 'str', retrieved_at: 'datetime', sha256: 'str', cache_stale: 'bool' = False, warning: 'str | None' = None)[source]#
No usable snapshot is available; callers must not substitute demo data.
- class space_pv_connectors.gp_cache.GPCache(path)[source]#
Cache provider queries for at least two hours, including across restarts.
SQLite serializes downloads from processes sharing this local file. Any HTTP or malformed-response error pauses the entire provider until an operator calls
resume(). Existing snapshots remain available with an explicit warning; the orbit layer separately rejects old element epochs.Share one cache per deployment, on a local filesystem. Multiple hosts need a single ingestion service, not independent caches behind the same IP.
- Parameters:
path (str | Path)
N2YO positions#
Optional server-side N2YO calculated-position connector.
- class space_pv_connectors.n2yo.N2YOConnector(*, api_key=None, timeout_s=30)[source]#
N2YO REST v1. Keep API keys on the server, outside browser bundles.
Positions are provider predictions, not satellite GPS telemetry. The free service documents 1,000 position calls/hour and at most 300 samples/call. No retries are made here. Bulk tracking should use cached GP + local SGP4. https://www.n2yo.com/api/
Array procurement inputs#
Load auditable array-trade inputs using the shared tabular connector.
- space_pv_connectors.procurement.load_array_offers(path)[source]#
Load CSV/Excel/Parquet offers without converting efficiency or units.
Required numeric columns are array-level BOL W/m², EOL retention, kg/m², and procurement currency/m². Currency and EOL duration must be common and documented externally. Source links establish provenance, not validation. Evidence status is measured, imported, modeled, or synthetic; all nonempty text and extra metadata columns are preserved.
Version-pinned arXiv literature#
Version-pinned arXiv metadata with original-byte provenance and offline cache.
- space_pv_connectors.arxiv.parse_arxiv_atom(content, paper_id)[source]#
Parse one exact-version Atom entry; never silently substitute latest.
- class space_pv_connectors.arxiv.ArxivConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#
One explicit paper per request; reuse cache and observe arXiv rate limits.
The original Atom bytes are cached with SHA-256, URL and retrieval time. This connector does not extract or promote scientific claims from PDFs. Downloading an accessible paper does not grant redistribution rights.