{"openapi":"3.1.0","info":{"title":"Macroscope API","version":"1.0.0","description":"Открытые данные Макроскопа о демографии 237 стран: ООН World Population Prospects 2024 (оценки 1950–2023 и прогноз до 2100), национальная статистика 64 стран за 2015–2025, архивы официальных прогнозов, сверенные с фактом, и когортная модель сценариев. Без ключа и регистрации.\n\nOpen Macroscope data on the demography of 237 countries: UN World Population Prospects 2024 (estimates 1950–2023, projections to 2100), national statistics of 64 countries for 2015–2025, archived official projections checked against actual data, and the cohort scenario model. No key or sign-up.\n\nMCP: https://macroscope.reasonful.com/mcp","license":{"name":"UN WPP data: CC BY 3.0 IGO","url":"https://creativecommons.org/licenses/by/3.0/igo/"}},"servers":[{"url":"https://macroscope.reasonful.com"}],"externalDocs":{"description":"llms.txt","url":"https://macroscope.reasonful.com/llms.txt"},"paths":{"/api/v1/":{"get":{"operationId":"api_index","summary":"Описание API / API overview","responses":{"200":{"description":"API overview","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/locations":{"get":{"operationId":"search_locations","summary":"Найти страну или регион / Find a country or region","description":"Ищет страны и регионы (237 стран, мир, регионы ООН, группы по доходу, ЕС) по названию на русском или английском или по коду и возвращает коды для других запросов. / Finds countries and regions by name or code and returns the codes used by other calls.","parameters":[{"name":"query","in":"query","required":false,"description":"Часть названия или код; пусто — все / part of a name or a code; empty = all","schema":{"type":"string","description":"Часть названия или код; пусто — все / part of a name or a code; empty = all"}},{"name":"type","in":"query","required":false,"description":"Тип / type","schema":{"type":"string","enum":["country","world","region","subregion","sdg","income","dev","union"],"description":"Тип / type"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":300,"default":50}},{"name":"lang","in":"query","required":false,"description":"Язык названий и пояснений / language of names and notes","schema":{"type":"string","enum":["ru","en"],"default":"ru","description":"Язык названий и пояснений / language of names and notes"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/locations/{location}":{"get":{"operationId":"get_location","summary":"Профиль страны или региона / Location profile","description":"Главное о стране или регионе: последняя рождаемость и рождения с источником, пик рождений, ключевые значения ООН (1950–2100), национальная статистика с примечаниями, сверка с прогнозом ООН-2024, связанные случаи «прогноз против факта». / Key facts with sources, UN values 1950–2100, national statistics, UN-2024 check and related forecast cases.","parameters":[{"name":"location","in":"path","required":true,"description":"Страна или регион: название по-русски или по-английски, ISO3 (KOR), код региона (un-900 — мир) / country or region: name, ISO3 or region code","schema":{"type":"string","description":"Страна или регион: название по-русски или по-английски, ISO3 (KOR), код региона (un-900 — мир) / country or region: name, ISO3 or region code"}},{"name":"lang","in":"query","required":false,"description":"Язык названий и пояснений / language of names and notes","schema":{"type":"string","enum":["ru","en"],"default":"ru","description":"Язык названий и пояснений / language of names and notes"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/indicators":{"get":{"operationId":"list_indicators","summary":"Показатели и единицы / Indicators and units","description":"Список показателей (население, рождения, рождаемость, продолжительность жизни, миграция, медианный возраст, нагрузка пожилыми…) с единицами, годами и видами рядов. / Indicators with units, years and series kinds.","parameters":[{"name":"lang","in":"query","required":false,"description":"Язык названий и пояснений / language of names and notes","schema":{"type":"string","enum":["ru","en"],"default":"ru","description":"Язык названий и пояснений / language of names and notes"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/series":{"get":{"operationId":"get_series","summary":"Временные ряды / Time series","description":"Ряды показателей по странам: оценки ООН 1950–2023, варианты прогноза ООН до 2100 года и национальная статистика со ссылками на источники. До 10 стран и 6 показателей за запрос. / Indicator time series: UN estimates, UN projection variants and national statistics with sources.","parameters":[{"name":"location","in":"query","required":true,"description":"Одна или несколько через запятую: KOR,JPN / one or more, comma-separated","schema":{"type":"string","description":"Одна или несколько через запятую: KOR,JPN / one or more, comma-separated"}},{"name":"indicator","in":"query","required":true,"description":"Через запятую: births,tfr,population… (см. list_indicators) / comma-separated ids","schema":{"type":"string","description":"Через запятую: births,tfr,population… (см. list_indicators) / comma-separated ids"}},{"name":"from_year","in":"query","required":false,"schema":{"type":"integer","minimum":1950,"maximum":2100,"default":1950}},{"name":"to_year","in":"query","required":false,"schema":{"type":"integer","minimum":1950,"maximum":2100,"default":2100}},{"name":"kind","in":"query","required":false,"description":"Через запятую: estimate, projection_medium, projection_low, projection_lower95, projection_upper95, national или all; по умолчанию estimate,projection_medium,national","schema":{"type":"string","description":"Через запятую: estimate, projection_medium, projection_low, projection_lower95, projection_upper95, national или all; по умолчанию estimate,projection_medium,national"}},{"name":"lang","in":"query","required":false,"description":"Язык названий и пояснений / language of names and notes","schema":{"type":"string","enum":["ru","en"],"default":"ru","description":"Язык названий и пояснений / language of names and notes"}},{"name":"format","in":"query","required":false,"description":"csv — таблица вместо JSON / csv for a table","schema":{"type":"string","enum":["json","csv"],"default":"json","description":"csv — таблица вместо JSON / csv for a table"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/countries":{"get":{"operationId":"rank_countries","summary":"Сравнить страны / Rank countries","description":"Таблица 237 стран: последняя рождаемость и рождения, падение от пика, население 2024, прогноз ООН на 2100 год, медианный возраст, нагрузка пожилыми; сортировка, фильтр по региону и размеру. / Country table with sorting and filters.","parameters":[{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","enum":["tfr_latest","births_latest_k","births_change_from_peak_pct","peak_births_k","population_2024_k","un_medium_population_2100_k","un_medium_change_2024_2100_pct","un_low_change_2024_2100_pct","median_age_2024","old_age_dependency_2025","old_age_dependency_2050","name"],"default":"tfr_latest"}},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"asc"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":237,"default":20}},{"name":"region","in":"query","required":false,"description":"Регион: un-908 Европа, un-935 Азия, un-903 Африка… / region code or name","schema":{"type":"string","description":"Регион: un-908 Европа, un-935 Азия, un-903 Африка… / region code or name"}},{"name":"group","in":"query","required":false,"description":"hardest_cases — очень низкая рождаемость; largest — 30 крупнейших","schema":{"type":"string","enum":["hardest_cases","largest"],"description":"hardest_cases — очень низкая рождаемость; largest — 30 крупнейших"}},{"name":"min_population_k","in":"query","required":false,"description":"Население 2024 не меньше, тыс. / minimum population 2024, thousands","schema":{"type":"number","minimum":0,"description":"Население 2024 не меньше, тыс. / minimum population 2024, thousands"}},{"name":"lang","in":"query","required":false,"description":"Язык названий и пояснений / language of names and notes","schema":{"type":"string","enum":["ru","en"],"default":"ru","description":"Язык названий и пояснений / language of names and notes"}},{"name":"format","in":"query","required":false,"description":"csv — таблица вместо JSON / csv for a table","schema":{"type":"string","enum":["json","csv"],"default":"json","description":"csv — таблица вместо JSON / csv for a table"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/forecasts":{"get":{"operationId":"list_forecast_cases","summary":"Случаи «прогноз против факта» / Forecast-vs-actual cases","description":"22 случая, где архивы официальных прогнозов (IPSS, статистика Кореи и Тайваня, ООН, SSA, ONS, Евростат, Destatis, ISTAT, Росстат…) сверены с фактом. / 22 cases of archived official projections checked against actual data.","parameters":[{"name":"lang","in":"query","required":false,"description":"Язык названий и пояснений / language of names and notes","schema":{"type":"string","enum":["ru","en"],"default":"ru","description":"Язык названий и пояснений / language of names and notes"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/forecasts/{case_id}":{"get":{"operationId":"get_forecast_case","summary":"Прогнозы и факт по случаю / One forecast case","description":"Фактический ряд, все архивные прогнозы и разбор каждого: что ждали на последний год с фактом, расхождение, в каком году прогноз ждал сегодняшнего уровня. / Actual series, archived projections and a check of each.","parameters":[{"name":"case_id","in":"path","required":true,"description":"Например jpn_births, kor_tfr, chn_un (см. list_forecast_cases)","schema":{"type":"string","description":"Например jpn_births, kor_tfr, chn_un (см. list_forecast_cases)"}},{"name":"lang","in":"query","required":false,"description":"Язык названий и пояснений / language of names and notes","schema":{"type":"string","enum":["ru","en"],"default":"ru","description":"Язык названий и пояснений / language of names and notes"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/un2024-vs-actual":{"get":{"operationId":"get_un2024_vs_actual","summary":"Прогноз ООН-2024 против фактических рождений / UN 2024 vs actual births","description":"По 47 странам с данными за 2024–2025 годы: рождения по среднему варианту ООН (июль 2024) против национальной статистики, расхождение и выход за 95%-интервал. / UN medium variant vs national births for 47 countries.","parameters":[{"name":"location","in":"query","required":false,"description":"Необязательно: одна страна / optional single country","schema":{"type":"string","description":"Необязательно: одна страна / optional single country"}},{"name":"lang","in":"query","required":false,"description":"Язык названий и пояснений / language of names and notes","schema":{"type":"string","enum":["ru","en"],"default":"ru","description":"Язык названий и пояснений / language of names and notes"}},{"name":"format","in":"query","required":false,"description":"csv — таблица вместо JSON / csv for a table","schema":{"type":"string","enum":["json","csv"],"default":"json","description":"csv — таблица вместо JSON / csv for a table"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/findings":{"get":{"operationId":"get_key_findings","summary":"Главные выводы / Key findings","description":"Главные выводы Макроскопа, посчитанные из данных (те же, что на сайте). / Key findings computed from the data.","parameters":[{"name":"lang","in":"query","required":false,"description":"Язык названий и пояснений / language of names and notes","schema":{"type":"string","enum":["ru","en"],"default":"ru","description":"Язык названий и пояснений / language of names and notes"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sources":{"get":{"operationId":"get_sources","summary":"Источники / Sources","description":"Первоисточники: ООН WPP 2024, национальные статистические ведомства, архивы прогнозов; можно отфильтровать по стране. / Primary sources, optionally for one country.","parameters":[{"name":"location","in":"query","required":false,"description":"Необязательно / optional","schema":{"type":"string","description":"Необязательно / optional"}},{"name":"lang","in":"query","required":false,"description":"Язык названий и пояснений / language of names and notes","schema":{"type":"string","enum":["ru","en"],"default":"ru","description":"Язык названий и пояснений / language of names and notes"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/scenario":{"get":{"operationId":"run_scenario","summary":"Посчитать сценарий / Run a scenario","description":"Когортная модель Макроскопа (та же, что в калькуляторе): население, рождения, возрастные группы, нагрузка пожилыми и медианный возраст с 2024 года до 2300-го при заданной рождаемости, смертности и миграции, плюс сравнение со средним вариантом ООН. Сценарий — арифметика, а не прогноз. / The calculator's cohort model: population, births, age groups, old-age dependency to 2300 under given assumptions, compared with the UN medium variant.","parameters":[{"name":"location","in":"query","required":true,"description":"Страна или регион: название по-русски или по-английски, ISO3 (KOR), код региона (un-900 — мир) / country or region: name, ISO3 or region code","schema":{"type":"string","description":"Страна или регион: название по-русски или по-английски, ISO3 (KOR), код региона (un-900 — мир) / country or region: name, ISO3 or region code"}},{"name":"fertility","in":"query","required":false,"description":"freeze — последний факт навсегда; trend — продолжение темпа последних лет до дна; custom — к цели к году; un / low — варианты ООН","schema":{"type":"string","enum":["freeze","trend","custom","un","low"],"default":"freeze","description":"freeze — последний факт навсегда; trend — продолжение темпа последних лет до дна; custom — к цели к году; un / low — варианты ООН"}},{"name":"fertility_target","in":"query","required":false,"description":"Для custom: детей на женщину / target TFR","schema":{"type":"number","minimum":0.3,"maximum":3,"description":"Для custom: детей на женщину / target TFR"}},{"name":"fertility_by_year","in":"query","required":false,"description":"Для custom: к какому году / target year","schema":{"type":"integer","minimum":2026,"maximum":2300,"description":"Для custom: к какому году / target year"}},{"name":"trend_window","in":"query","required":false,"description":"Для trend: окно, лет","schema":{"type":"integer","minimum":3,"maximum":20,"default":10,"description":"Для trend: окно, лет"}},{"name":"trend_floor","in":"query","required":false,"description":"Для trend: дно","schema":{"type":"number","minimum":0.3,"maximum":1.6,"default":0.6,"description":"Для trend: дно"}},{"name":"mortality","in":"query","required":false,"description":"un — как у ООН; freeze — уровень 2024; shift — сдвиг продолжительности жизни к 2100","schema":{"type":"string","enum":["un","freeze","shift"],"default":"un","description":"un — как у ООН; freeze — уровень 2024; shift — сдвиг продолжительности жизни к 2100"}},{"name":"mortality_shift","in":"query","required":false,"description":"Для shift: лет к 2100","schema":{"type":"number","minimum":-10,"maximum":10,"description":"Для shift: лет к 2100"}},{"name":"migration","in":"query","required":false,"schema":{"type":"string","enum":["un","zero","custom"],"default":"un"}},{"name":"migration_per_year","in":"query","required":false,"description":"Для custom: нетто-миграция, тыс. в год","schema":{"type":"number","minimum":-5000,"maximum":5000,"description":"Для custom: нетто-миграция, тыс. в год"}},{"name":"to_year","in":"query","required":false,"schema":{"type":"integer","minimum":2030,"maximum":2300,"default":2100}},{"name":"step","in":"query","required":false,"description":"Шаг строк, лет / row step, years","schema":{"type":"integer","minimum":1,"maximum":50,"default":5,"description":"Шаг строк, лет / row step, years"}},{"name":"lang","in":"query","required":false,"description":"Язык названий и пояснений / language of names and notes","schema":{"type":"string","enum":["ru","en"],"default":"ru","description":"Язык названий и пояснений / language of names and notes"}},{"name":"format","in":"query","required":false,"description":"csv — таблица вместо JSON / csv for a table","schema":{"type":"string","enum":["json","csv"],"default":"json","description":"csv — таблица вместо JSON / csv for a table"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}