femic.bcdc_dwds Module

The femic.bcdc_dwds module owns FEMIC’s heavier BCGW fallback lane for BCDC datasets that need a DWDS order instead of a direct download or a WFS-backed subset fetch. It sits beside femic.bcdc_fetch: resolve and prefer WFS first, then use DWDS when the dataset needs a warehouse order and a richer output format such as File Geodatabase or GeoPackage.

Use this page when you are debugging the public DWDS order payload, FGDB/GPKG format selection, or the status/manifest caveats of the current public seam. In particular, this is where to start if you need to understand why the public /order/{id} seam did not return a clean live status after a successful order submission, or how FEMIC follows up on an existing DWDS manifest to retry the status probe and materialize the artifact when a download URL appears. This now also covers the stronger retrieval seam discovered in live TSA29 use:

  • DWDS may email an pickupByGUID launcher URL rather than exposing a clean public /order/{id} download URL;

  • that launcher page is HTML, not the final package; and

  • FEMIC can now follow the launcher to the real distribution.data.gov.bc.ca zip when the order has been assembled.

Start Here If…

Use this page first if you are trying to:

  • inspect how FEMIC builds a custom GML AOI from a bbox or Geomark-derived bbox;

  • debug the public createOrderFiltered payload for a BCGW feature type;

  • understand why a bcdc-order call chose FGDB vs GeoPackage output; or

  • inspect the current caveat that the public /order/{id} seam may not resolve successful live orders cleanly, even though bcdc-order-followup can now retry that seam later and, when necessary, pivot through the emailed pickupByGUID launcher page to materialize the artifact.

  • understand how FEMIC resolves the DWDS notification email when --email is omitted (explicit flag first, then FEMIC_BCDC_DWDS_EMAIL, then git config user.email).

Typical Usage

The common operator-facing entrypoint is:

femic data bcdc-order WHSE_FOREST_VEGETATION.F_OWN --bbox 1170000,450000,1180000,460000

The matching Python entrypoints are:

from pathlib import Path
from femic.bcdc_dwds import (
    follow_up_bcdc_dwds_order,
    load_bcdc_dwds_manifest,
    submit_bcdc_dwds_order,
    write_bcdc_dwds_manifest,
)

result = submit_bcdc_dwds_order(
    "WHSE_FOREST_VEGETATION.F_OWN",
    bbox_epsg3005=(1170000.0, 450000.0, 1180000.0, 460000.0),
    output_format="fgdb",
)
write_bcdc_dwds_manifest(result, Path("runtime/logs/f_own_dwds_manifest.json"))

saved = follow_up_bcdc_dwds_order(
    load_bcdc_dwds_manifest(Path("runtime/logs/f_own_dwds_manifest.json"))[0],
    download_root=Path("downloads/bcdc"),
)
write_bcdc_dwds_manifest(saved, Path("runtime/logs/f_own_dwds_manifest.json"))

Key Entry Surfaces

  • submit_bcdc_dwds_order() Resolve a BCDC query, choose a BCGW feature type, and submit a public DWDS order for FGDB/GPKG/GeoJSON/shapefile output.

  • load_bcdc_dwds_manifest() Reload one or more previously submitted DWDS orders from a FEMIC manifest.

  • follow_up_bcdc_dwds_order() Re-probe one submitted DWDS order and materialize its artifact when DWDS exposes a download URL, or when the saved order_guid can be used to resolve the emailed pickupByGUID launcher page into the real distribution zip URL.

  • write_bcdc_dwds_manifest() Persist one DWDS order result as JSON for later review or follow-up retries.

Cross-References

DWDS fallback helpers for BC Data Catalogue feature-type orders.

exception femic.bcdc_dwds.BcdcDwdsError[source]

Bases: RuntimeError

Raised when a DWDS fallback order cannot be created or interpreted.

class femic.bcdc_dwds.BcdcDwdsOrderResult(query, limit, generated_utc, package_id, package_name, package_title, dataset_page_url, resource_id, resource_name, resource_url, feature_type, matched_by, aoi_source, bbox_epsg3005, geomark_id, geomark_url, output_format, email_address, clipping_method, ordering_application, request_url, request_payload, order_id, order_guid, submission_status, submission_description, submission_value, status_probe, warnings=(), latest_followup_utc=None, latest_followup_status_probe=None, latest_followup_pickup_url=None, latest_followup_pickup_download_url=None, materialized_artifact_path=None, materialized_download_url=None, materialized_content_type=None, materialized_bytes=None, followup_warnings=())[source]

Bases: object

One DWDS order submission result for a resolved BCDC query.

Parameters:

  • query (str)

  • limit (int)

  • generated_utc (str)

  • package_id (str)

  • package_name (str)

  • package_title (str)

  • dataset_page_url (str)

  • resource_id (str)

  • resource_name (str)

  • resource_url (str | None)

  • feature_type (str)

  • matched_by (str)

  • aoi_source (str)

  • bbox_epsg3005 (tuple[float, float, float, float])

  • geomark_id (str | None)

  • geomark_url (str | None)

  • output_format (str)

  • email_address (str | None)

  • clipping_method (str)

  • ordering_application (str)

  • request_url (str)

  • request_payload (dict[str, object])

  • order_id (str)

  • order_guid (str | None)

  • submission_status (str)

  • submission_description (str)

  • submission_value (str | None)

  • status_probe (BcdcDwdsStatusProbe | None)

  • warnings (tuple[str, ...])

  • latest_followup_utc (str | None)

  • latest_followup_status_probe (BcdcDwdsStatusProbe | None)

  • latest_followup_pickup_url (str | None)

  • latest_followup_pickup_download_url (str | None)

  • materialized_artifact_path (str | None)

  • materialized_download_url (str | None)

  • materialized_content_type (str | None)

  • materialized_bytes (int | None)

  • followup_warnings (tuple[str, ...])

aoi_source: str
bbox_epsg3005: tuple[float, float, float, float]
clipping_method: str
dataset_page_url: str
email_address: str | None
feature_type: str
followup_warnings: tuple[str, ...] = ()
generated_utc: str
geomark_id: str | None
geomark_url: str | None
latest_followup_pickup_download_url: str | None = None
latest_followup_pickup_url: str | None = None
latest_followup_status_probe: BcdcDwdsStatusProbe | None = None
latest_followup_utc: str | None = None
limit: int
matched_by: str
materialized_artifact_path: str | None = None
materialized_bytes: int | None = None
materialized_content_type: str | None = None
materialized_download_url: str | None = None
order_guid: str | None
order_id: str
ordering_application: str
output_format: str
package_id: str
package_name: str
package_title: str
query: str
request_payload: dict[str, object]
request_url: str
resource_id: str
resource_name: str
resource_url: str | None
status_probe: BcdcDwdsStatusProbe | None
submission_description: str
submission_status: str
submission_value: str | None
to_dict()[source]
Return type:

dict[str, object]

warnings: tuple[str, ...] = ()
class femic.bcdc_dwds.BcdcDwdsStatusProbe(order_id, raw_payload, status, description, value, download_url)[source]

Bases: object

One post-submission probe against the public DWDS order-status seam.

Parameters:

  • order_id (str)

  • raw_payload (dict[str, Any])

  • status (str | None)

  • description (str | None)

  • value (str | None)

  • download_url (str | None)

description: str | None
download_url: str | None
order_id: str
raw_payload: dict[str, Any]
status: str | None
to_dict()[source]
Return type:

dict[str, object]

value: str | None
femic.bcdc_dwds.follow_up_bcdc_dwds_order(order_result, *, download_root=None, poll_status=True)[source]

Re-probe a submitted DWDS order and materialize its artifact when ready.

Parameters:
Return type:

BcdcDwdsOrderResult

femic.bcdc_dwds.load_bcdc_dwds_manifest(path)[source]

Load one or more DWDS order results from a previously written manifest.

Parameters:

path (Path)

Return type:

list[BcdcDwdsOrderResult]

femic.bcdc_dwds.submit_bcdc_dwds_order(query, *, bbox_epsg3005, output_format='fgdb', limit=5, geomark=None, email_address=None, clip_to_aoi=True, poll_status=True, ordering_application='FEMIC-BCDC-DWDS')[source]

Submit a public DWDS order for the top-ranked BCDC package match.

Parameters:

  • query (str)

  • bbox_epsg3005 (tuple[float, float, float, float])

  • output_format (str)

  • limit (int)

  • geomark (GeomarkBBox | None)

  • email_address (str | None)

  • clip_to_aoi (bool)

  • poll_status (bool)

  • ordering_application (str)

Return type:

BcdcDwdsOrderResult

femic.bcdc_dwds.write_bcdc_dwds_manifest(results, path)[source]

Write one or more DWDS order results to a JSON manifest.

Parameters:
Return type:

Path