Availability follows the selected, published source release. Check
meta.coverage for source editions, reference periods, measured geography and participant coverage. An unpublished release returns 503 SOURCE_UNAVAILABLE; it is not an empty inventory. MCP tools require the matching deployed server contract; a REST release alone does not add tools to an older MCP server. Available archived inputs do not imply a historical-vintage API.Where to access the data
Facilities and mineral statistics require
can_use_facilities; detailed Epoch observations require can_use_epoch_ai, and GEM finance requires can_use_gem. A withheld collection is not evidence of no records. See the API reference and MCP tools for current schemas and access requirements.
Find U.S. mineral facilities
These are request recipes; returned records depend on the published release and your access. SetGDELT_API_KEY to your key. Replace the base URL with your local API origin when testing.
usgs_myb supplies international facilities and excludes the United States; that exclusion does not apply to the domestic source or MCS country statistics. Source reference dates are separate from the API release date. A directory refresh can advance last_seen_date without introducing new source observations; use native observation dates and reference years when assessing source freshness.
commodity matches the canonical site’s normalized commodity keys. Discover the currently measured keys through GET /api/v2/meta/enums (facility_commodity) or the observed vocabulary reference. The list is drawn from the current published facility registry and is a measured suggestion, not an allowlist; new keys remain valid filters.
The default granularity=site returns canonical sites. Use granularity=unit for registry units, and copy the returned facility_id into detail requests. A mine and its neighboring processing plant remain separate assets unless their physical identity is established. Source files may report a town or state without coordinates: lat and lon can be null. has_geo=true requires both coordinates; inspect geo_precision and geo_evidence before treating a point as an exact location.
Rank facilities by recent news
sort=news_activity parameter works with MCP facilities_search. Facilities Explore uses it by default; the REST API preserves its name default. sort=recent means latest directory updates, not news activity.
News activity ranks the entire filtered directory before pagination, using seven recent days of served canonical Events. Direct owner identities explicitly linked on Event cards rank first; ties rank by the distinct union of those matches and Events within 25 km, then latest Event date, name and facility ID. This prioritizes a recorded entity connection over proximity alone. Parent rollups are excluded from this ranking; the facility context endpoint offers broader owner and parent discovery.
Each card includes news_activity.observed_event_count, owner_event_count, nearby_event_count and latest_event_date. The two component counts can overlap: an Event matching both scopes counts once in observed_event_count. No resolved owner or no point geography leaves that component null. A zero is only a measured lack of matches in the admitted snapshot dates, not proof of no reporting or no real-world activity.
meta.news_activity discloses served_dates, withheld and awaiting dates, the effective window and any relative-window adjustment, snapshot time and completeness. snapshot_identity identifies every contributing serving partition; rankings can change when a new snapshot arrives, so compare it between pages and restart pagination if your workflow requires one consistent ranking. Ranking reads serving tables only and returns a retryable service error if ranking is unavailable. Nearby reporting does not establish an incident or impact at the facility; retain coordinate precision and inspect supporting Events through the context endpoint.
Read rare-earth reserves without assigning them to mines
country, region and continent vocabulary as Events. Country accepts names, ISO-2/ISO-3 codes and comma-separated countries; country_iso3 is an alternative parameter, not a second geographic scope. Geography filters select country-scoped observations and exclude aggregate and unresolved observations. Use scope=aggregate without a geographic filter for publisher aggregate series. source and scope are closed enums. Commodity and statistic suggestions in the Arena and /api/v2/meta/enums are observed vocabulary: a new key is accepted and can return an empty result. statistic_detail, material_type and material_form select exact native measures. year selects the source reference year, independently of news dates.
With include_summary=true, meta.summary counts the full filtered result before pagination: observations, non-null numeric values, null values, countries in country-scoped observations, reference-year bounds and source/scope/statistic/qualifier/commodity facets. Commodity facets retain source and scope. These are observation counts, not quantities of minerals or deposits. The endpoint never sums unlike years, materials or units; data preserves every individual measure and qualifier. A null value can mean unknown, suppressed, qualitative or not applicable—read its qualifier and original text.
For example, /api/v2/resources/statistics?continent=Asia&statistic=production&include_summary=true gives regional count facets and a paginated preview of original production observations. The Natural-resource statistics Arena tool provides searchable commodity/statistic suggestions, geographic choices and atomic measure cards. Facilities tools display native observations and typed physical/participant relationships with separate pagination and source evidence.
GET /api/v2/countries/{iso3} includes natural_resources: up to twelve country-scoped observations, the full-result count summary, source coverage, pagination and api_url for the complete collection. Country pages show this in Economy & Resources. Missing or withheld resource coverage is explicit in section_availability.natural_resources; it is not zero. Public country editions retain their captured resource data, while authenticated live country context reads the current selected release.
The named MCP tool resource_statistics(continent="Asia", statistic="production", include_summary=true) exposes the same response. Use the advertised schema for exact filters; optional get_parameter_options explains uncertain choices.
Diamond series retain natural/synthetic and gem/industrial distinctions in their commodity keys and native descriptions. For example, commodity=diamond_industrial selects that normalized series; inspect its unit and native qualifiers before comparing it with diamond or other diamond forms. The selected sources do not provide a complete deposit census, water inventories, aquifers, water rights or forest resources. Existing country water indicators are separate context.
Inspect overlap with GEM
Search withsource=gem or another contributing source. A fused site’s source_memberships retains every admitted contributing source even when the request filters on one. Follow its observations_url to inspect original records and relationships_url to inspect participants and physical links. Source units and aliases remain traceable to the canonical site.
Follow a participant through the entity spine
Resolve the organization throughGET /api/v2/search?q=Microsoft&type=organization, inspect the candidates, and select its entity_id. Use that returned identifier across endpoints:
GET /api/v2/facilities?entity={entity_id}selects recorded ownership.GET /api/v2/facilities?participant_entity={entity_id}&participant_role=operatorselects an explicit participant role.GET /api/v2/epoch/gpu-clusters?entity={entity_id}&participant_role=ownerselects cluster ownership evidence.
participant_entity matches a resolved spine identity in a source participant assertion; it is separate from the owner filters. participant_role is an exact, open-vocabulary value as published by that source. The assertion and its evidence describe the source’s role claim, not verified ownership or control. Facility cards may include matched_participation with at most 25 matching assertions per site and truncated when more exist. Entity detail can include a separate reverse facilities.participation preview of at most six sites with a cursor; it is not a complete participant portfolio count. Neither participant view is inherited through a corporate parent.
For news, use /api/v2/events?entity={entity_id} or the site’s /context endpoint. The latter provides bounded owner/parent reporting with typed relationship paths. It does not establish that the reporting occurred at or affected the facility. Read news date coverage separately from registry editions.
meta.coverage.partial_owner_scope is true when recorded owners remain unresolved, the owner probe is truncated, or a parent lookup fails. A resolved owner can supply useful news context while other owners remain outside the measured scope. Keep their null entity IDs and names visible rather than treating the context as complete ownership coverage.
Get a joined reporting view in one request
facility, owner.coverage_paths, owner_events and owner_stories. With include=nearby, it also returns nearby_events and nearby_stories for a geographic screen. Recorded parents are considered for each unbridged owner, including when another owner bridges directly. A minority stake does not establish control. Nearby Events are leads around the recorded coordinates, not confirmed incidents at or affecting the site.
Read meta.coverage.reporting for owner reporting dates and meta.nearby_coverage.reporting for nearby reporting dates. window_complete: false means some dates remain unavailable. null arrays mean a scope could not be measured; empty arrays mean the available reporting was searched without matches. Nearby coverage discloses coordinate precision and uses the requested window; owner reporting can expand an empty short window to 30 days, with the effective window labeled.
Facilities Explore starts with News activity (7 days), using the ranking and coverage described above. Latest directory updates remains available and orders the directory by last_seen_date. Expand Explore owner and nearby reporting for a bounded preview or open the facility detail for the joined view. Each reporting collection offers Monitor this and Use this data with its own scope. Linked-Story monitors follow the underlying Events and their Story links. Registry observations and participant relationships offer API inspection; their Monitor control explains that these directory collections have no standing-query form.
A named owner with no entity_id is displayed as a reported owner, with an active profile link opening in a new tab. The context endpoint looks up name-only owners through the shared reference resolver, accepting only one terminal entity with an exact name or alias match. It returns reported_owner_matches with match status and evidence basis, plus separate reported_owner_events and reported_owner_stories. meta.reported_owner_coverage discloses the measured identities, exact dates and partial name scope. Ambiguous, fuzzy and unavailable matches never become ownership links or measured zeroes. This discovery does not verify facility ownership; facility.owners[].entity_id, owner_events, resolved-owner coverage and news-activity ranking keep their existing meanings.
Individual facility pages reuse the Arena’s themed Event and Story cards and existing Entity cards for owners, participants and related identities. Unknown card metrics are omitted. The header’s Monitor this prepares an Event scope for measured linked owners, then measured reported owners, or otherwise a valid geographic point; its description states that basis. Signed-out readers retain the draft through sign-in. Without a linked reporting identity or usable coordinates, the control explains why it is disabled.
Individual facility pages place a borderless city-scale map beside the name. Left-aligned reporting-window buttons sit immediately above the summary cards and show Working feedback while the measured reporting window reloads. Source participants appear near the top, before news reporting: for Epoch AI data centers, these are the original Owner and Users fields, not Event actors. A compact overview of one linked owner uses the existing GET /api/v2/entities/{entity_id} response to show distinct SEC CIKs, tickers, matched global-list entries and contributing list sources. These are identifier and membership counts, not filing totals or a sanctions decision. With registry and exposure access, the entity response also includes corporate_context: recorded immediate parents and children with typed relationships, source evidence and observation dates. The owner overview shows parent-company SEC and global-list counts separately, attributed to the named parent; it never transfers those records or designations to the subsidiary. Parent SEC and list summaries retain their own source entitlements. At most 100 assertions in either direction and five parent summaries are returned, with explicit truncation and unavailable states. Missing corporate edges do not establish that a company is independent. GLEIF consolidation, legal subsidiary relationships and ownership interests remain distinct. Parent and subsidiary links open the recorded entity profiles in new tabs. MCP get_entity(include_registry=true) exposes the same response on servers carrying this wrapper update. Source access and unavailable measurements remain explicit; all recorded owners remain available in the lower record details. Use this data exposes the exact entity response as well as the facility collection responses. Reported-owner and nearby reporting follow. Reporting collections initially show two cards, with an expand/collapse control for the rest and Monitor this and Use this data at the top. All returned participant profiles are visible together in responsive columns; the underlying API collection remains paginated. Roles combine only for the same identified profile while preserving every source assertion. Event and Story identity references render linked Entity profiles. Descriptive actors such as unnamed victims remain plain Event text and do not become entity search links. The context endpoint supplements actor identities through unambiguous existing or linked-Story evidence, then unique exact reference-name or alias matches. Recognized office or honorific prefixes on named people can be removed for an exact identity match, so “Sen. Roger Wicker” can bind to Roger Wicker’s verified person profile; anonymous descriptions remain unlinked. In its Event previews, actors[].entity_id points to an identity in entity_refs; unresolved descriptions have no identity field. Linked Stories are hydrated through the same serving API as /stories, preserving their actual topic categories, metrics and linked Event taxonomy evidence. Each scope’s story_details and actor_entities metadata disclose enrichment availability, serving dates, unresolved identities and bounded or failed lookups. Participants come from /relationships. The closed Facility record and ownership details section preserves the original /observations records, including source editions and separate native capacities. Those records can repeat the combined profile; they exist for provenance and comparison, not as additional facility totals. These are two additional API calls, independently paginated; the context endpoint remains the single joined reporting call. Use this data shows each executed collection response. Missing physical hierarchy links do not suppress participant records. The page uses a facility icon and site map when the loaded source records have no photograph. Empty owner placeholders are omitted; mixed linked and name-only owners remain visible. Owner, participant, Event, Story and related-entity links open in new tabs.
Explore and the Arena offer the published facility source filters from the same vocabulary as REST and MCP. USGS country resource statistics (usgs_mcs) are available through resource-statistics endpoints, not a facility source filter.
MCP’s facilities_context accepts include=["nearby"] and radius_km=25. The response preserves the REST scopes and coverage metadata. In owner.coverage_paths, relationship_role distinguishes direct owners, corporate parents and ownership links; an ownership stake does not establish corporate control. via identifies the lookup path.
Make the same requests through MCP
Call named tools directly using their advertised schemas. Useget_parameter_options for unfamiliar accepted choices. MCP uses typed arrays for Facilities source, country and commodity filters; REST uses comma-separated values. facility_class in MCP maps to REST’s class.
pagination.next_cursor with the same filters and check meta.coverage on every workflow. MCP discovery does not prove that a collection is published or that your plan can read it. Errors preserve the REST refusal; do not interpret a 403 PLAN_REQUIRED or 503 SOURCE_UNAVAILABLE as zero results.
For programmatic access, named tools return structured content. response_mode="compact" preserves selected evidence, identifiers, coverage, filters and pagination; response_mode="full" retains the bounded API response for builders. Neither mode fetches another page. Research results use normal chat text and client-supported tables or charts; account navigation and Monitor forms are the dedicated app components.
The Data & coverage page lists publishers, measured inventories and limitations; the data catalog retains attribution and source-specific rights.
Entity pages combine corporate structure, legal identity, crosswalked identifiers and business relationships in Company profile. Named canonical identities are resolved even when an edge stores a blank label. Recognized Wikipedia-linked companies appear first in the bounded corporate preview. Shareholders, owned companies and GLEIF accounting consolidation have distinct labels and source dates; an explicit source-reported ownership percentage is never inferred from consolidation. Facility cards name the selected company’s matched role (including parent owner) alongside direct facility owners. A parent-owner assertion does not establish an unreported intermediate corporate chain.
Signed-in Home offers dated asset, company and Story cards with one-click destinations. The three free Facilities examples open within the workspace for signed-in readers and remain public without a session. Examples are captures of actual API responses, not live or complete inventories. Topic Explore refreshes a rolling seven UTC calendar-day window using lexical search; date labels and counts describe the returned data.