Série longa de produção e reservas de minerais, por país e ano
Formato longo: uma linha por mineral, país, recorte e ano. É a rota para perguntas por PAÍS, do tipo 'quais minerais o Brasil produz' ou 'o que o Brasil tem de reservas', com `?country=BRA`, e também para a série histórica de um mineral com `?mineral=lithium&from=2021&to=2025`. Cada linha carrega o valor, a sentinela publicada quando não há valor (`value_raw`, `value_flag_reason`), a participação no total mundial com o motivo quando ela não existe (`share_of_world_pct` nulo + `share_basis`) e a edição da publicação. Edições diferentes não formam série comparável: o USGS reestima anos anteriores a cada safra. As linhas de total mundial ficam de fora por default. Sobre `reserves`: é estimativa geológica agregada por país, não reserva provada sob SEC S-K 1300, JORC ou NI 43-101.
In: header
Query Parameters
1001 <= value <= 1000Chave do mineral, ex.: lithium.
País em ISO 3166-1 alfa-3, ex.: BRA, CHN, AUS, CHL.
^[A-Za-z]{3}$"production" | "reserves"Ano exato.
1900 <= value <= 2100Ano inicial (inclusive).
1900 <= value <= 2100Ano final (inclusive).
1900 <= value <= 2100true inclui as linhas de total mundial, que por default ficam de fora por não serem um país.
Response Body
curl -X GET "https://api.databolsa.com/v1/minerals/observations?cursor=string&limit=100&mineral=string&country=string&statistic=production&year=1900&from=1900&to=1900&include_world_total=true"{
"data": [
{
"mineral": "string",
"label": "string",
"group": "string",
"country": "string",
"country_iso3": "string",
"country_label": "string",
"is_world_total": true,
"statistic": "string",
"statistic_detail": "string",
"statistic_detail_base": "string",
"unit": "string",
"year": 0,
"value": 0,
"value_raw": "string",
"value_flag": "string",
"value_flag_reason": "string",
"world_total": 0,
"world_total_flag": "string",
"countries_withheld": 0,
"is_estimate": true,
"is_critical": true,
"share_of_world_pct": 0,
"share_basis": "string",
"notes": "string",
"revision": "string",
"edition": "string",
"edition_year": 0
}
],
"meta": {
"next_cursor": "string",
"count": 0,
"total": 0,
"subject": {
"property1": "string",
"property2": "string"
}
}
}{
"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string"
}Ficha de um mineral
Perfil da commodity mineral: nome em português, grupo, se está na lista de minerais críticos do USGS, anos cobertos, unidades, quantos países aparecem e o maior produtor com sua participação. Ponto de entrada antes do ranking de países e da série histórica.
Ranking de países produtores e detentores de reservas de um mineral
Responde 'quem produz mais' e 'quem tem as maiores reservas': ranking de países produtores com a participação no total mundial, para lítio, cobre, nióbio, cobalto, terras raras, grafita, ferro, ouro, fosfato, potássio e as demais commodities do catálogo. Use `statistic=production` para produção do ano e `statistic=reserves` para reservas. É a rota certa para perguntas como 'quanto do nióbio do mundo vem do Brasil', 'quem domina a produção de terras raras' ou 'quais países concentram as reservas de lítio'. Como ler o resultado sem errar: - `share_of_world_pct` é NULO quando a participação não pode ser calculada, e `share_basis` diz o motivo. Nunca trate ausência como zero. O motivo mais sutil é `incomparable_basis`: existe total mundial, mas os países reportam bases diferentes, como nas reservas de boro, em que a Turquia declara boratos refinados, o Chile ulexita e a China óxido bórico equivalente. Não são somáveis, e é por isso que o próprio USGS marca o total como `XX`. - `meta.countries_withheld` acima de zero significa ranking INCOMPLETO: o USGS reteve o valor de países onde ele revelaria dado proprietário de empresa, então os shares não somam 100%. - `meta.is_estimate` verdadeiro significa que o ano é estimativa do USGS, não realizado. - Quando a commodity tem mais de um agregado (cobre tem produção de mina e produção de refino, com totais mundiais distintos), o ranking usa um recorte só e informa os outros em `meta.available_details`; troque com `?detail=`. - Em `statistic=reserves` o número é ESTIMATIVA GEOLÓGICA AGREGADA POR PAÍS publicada pelo USGS. Não é reserva provada ou provável declarada por companhia sob SEC S-K 1300, JORC ou NI 43-101, não tem a mesma auditoria e não deve ser comparada com o relatório técnico de uma mineradora.