Downloads¶

amf_download_data downloads AmeriFlux data through the route the AmeriFlux website uses: one request that tells the site PIs who is downloading and why¹. It runs only over stdio and needs a download identity. Inputs and result fields are in the Tool reference.

FLUXNET2015 and FLUXNET-CH4 files come from fluxnet.org's login-protected form, which ameriflux-mcp does not automate (feature_unavailable; see ameriflux://guide/fluxnet2015-access).

1. The plan¶

Without confirm, the tool returns a plan and sends nothing:

{"tool": "amf_download_data", "arguments": {"sites": ["AR-Bal", "CA-Let"], "product": "FLUXNET"}}

• disclosure: the request AmeriFlux would receive. The user ID, email and name show as configured (not shown); the intended-use category and the description appear in full, with [ameriflux-mcp] appended, because that is what the PIs read. recipients says who receives it: the PIs of each site and the AmeriFlux Data Download Log.
• eligible and ineligible: here CA-Let is ineligible, because it shares its data under the Legacy policy and the FLUXNET product is CC-BY-4.0 only.
• policy: the policy code to accept (CCBY4.0 or LEGACY), why, and its obligations. For BASE-BADM, one Legacy site makes the whole request Legacy, unless you ask for policy='CCBY4.0', which leaves the Legacy sites out.
• blockers and ready: what must be configured first (the identity, a complete profile, is_test).
• localCopies: matching files already in the download directory. A new request still notifies the PIs, so read those first if they are current.

2. Consent¶

The agent shows the user the plan. Only if they agree does it call again with confirm=true and accept_data_policy set to the plan's policy:

{"tool": "amf_download_data", "arguments": {"sites": ["AR-Bal"], "product": "FLUXNET", "accept_data_policy": "CCBY4.0", "confirm": true}}

The checks run in this order, and each fails before anything is sent: the product and policy combination, then the accepted policy (policy_not_accepted, policy_mismatch), then the identity (auth_required with identity_missing, profile_missing, profile_incomplete or is_test_unset), then at least one eligible site.

3. The transfer¶

AmeriFlux answers with links to static files on ftp.fluxdata.org². The server:

1. keeps only links on its allow-list (/.ameriflux_downloads/), with a plain file name, for a requested site; FLUXNET-BIF links are skipped, as amerifluxr does. Each skipped link is listed in skipped with the reason;
2. strips the ?=<user_id> tag from each link, so the file server never receives the identity. The file is the same with or without it;
3. sends a HEAD for the size and ETag, and checks downloads.max_file_bytes (1 GiB), downloads.max_bytes_per_call (2 GiB), downloads.max_files_per_call and the free disk space;
4. streams the file to <name>.part with If-Match, then checks that the ETag, the Content-Length and the byte count match the HEAD, and that every zip member passes its CRC;
5. moves it to <downloads.directory>/<product>/<name> and writes <name>.amf.json beside it.

A file that fails any check is not kept (status: failed, checksum_mismatch) and no .part file is left behind. With if_exists='skip' (the default) an existing file is kept, and identical says whether it matches the server copy; if_exists='replace' fetches it again unless it is identical.

What is written¶

~/ameriflux-downloads/
  FLUXNET/AMF_AR-Bal_FLUXNET_2012-2013_v1.3_r1.zip
  FLUXNET/AMF_AR-Bal_FLUXNET_2012-2013_v1.3_r1.zip.amf.json
  manifests/amf_download_20261024T120000Z_FLUXNET.json

Neither file holds the user ID, email, name or description. AmeriFlux also returns the PIs' contact emails: the result reports how many (piContactCount), and the emails are never stored or shown.

After the download¶

amf_preview_data(file=…) reads the zip in place, amf_read_bif(file=…) reads the site's BADM, and amf_get_citation gives the citations and obligations for the reference list. See Local files. To mirror the download folder to the CyVerse Data Store, see Sync downloads to CyVerse.