DA-22-01-2025--UN-Comtrade-API-get-data

Огляд пакету UN Comtrade API

https://github.com/uncomtrade/comtradeapicall

Пакет UN Comtrade API — це інструмент для спрощеного доступу до даних торгівельної статистики ООН. Ось основні особливості:

Головні функціональні можливості:

Отримання та попередній перегляд даних через функції previewFinalData, getFinalData, previewTarifflineData та getTarifflineData
Перевірка доступності даних використовуючи функції як getFinalDataAvailability та getTarifflineDataAvailability
Масове завантаження файлів через bulkDownloadFinalData та подібні функції
Асинхронне отримання даних для великих запитів (до 2,5 млн записів) з повідомленнями електронною поштою
Доступ до метаданих через функції getMetadata
Робота з довідковими даними через listReference та getReference
Отримання даних про стандартні вартості одиниць (SUV) через функцію getSUV
Доступ до експериментальних даних AIS (відстеження руху суден) через функцію getAIS

Критерії вибору даних:

Підтримується багато параметрів фільтрації, включаючи:

Тип продукту (товари або послуги)
Часовий інтервал (річний або місячний)
Класифікація продукту
Період часу
Код країни або географічної області
Код продукту та напрямок торгівлі (імпорт/експорт)

Встановлення та використання:

Встановлюється простою командою: pip install comtradeapicall
Вимагає Python 3.7 або вище
Підтримує використання через проксі-сервер

Особливості файлів:

Завантажені файли мають чітку систему найменування, що включає тип даних, країну, період та класифікацію, наприклад: COMTRADE-FINAL-CM504200003H1[2023-01-03]

Пакет значно спрощує роботу з API Comtrade, усуваючи необхідність вивчати всі кінцеві точки API та їхні параметри.

Проект аналізу міжнародних торговельних даних України

Опис проекту

Даний проект призначений для отримання, обробки та аналізу статистичних даних міжнародної торгівлі України з використанням UN Comtrade API. Проект фокусується на зборі детальної інформації про імпорт конкретних товарних груп за класифікацією Гармонізованої системи (HS).

Функціональність проекту

Основні можливості:

Отримання даних: Автоматизований збір даних про імпорт товарів в Україну за заданим товарним кодом через UN Comtrade API.
Часовий аналіз: Можливість отримати дані за будь-який період з січня 2019 року по квітень 2025 року з щомісячною деталізацією.
Збереження результатів: Автоматичне збереження отриманих даних у форматі JSON з метаданими про запит.
Оптимізація запитів: Механізм роботи з великими об'ємами даних через розбивку запитів за періодами.

Технічні деталі:

Ключовий товар: У поточній реалізації проект сфокусований на аналізі імпорту товару з кодом 310520 (мінеральні або хімічні добрива, що містять азот, фосфор і калій).
API обмеження: Обробка до 250 тисяч записів на один запит.
Метадані результатів: Включають інформацію про кількість рядків, код товару, час виконання запиту та часову мітку.

Технології

Python як основна мова програмування
pandas для маніпуляції з даними
comtradeapicall для взаємодії з UN Comtrade API
matplotlib для можливості подальшої візуалізації
JSON для зберігання та обміну даними

Можливості розширення

Проект можна розширити для:

Аналізу експортних операцій України
Порівняльного аналізу торгівлі з різними країнами-партнерами
Дослідження динаміки торгівлі за різними товарними групами
Створення інтерактивних візуалізацій та аналітичних звітів
Виявлення сезонних трендів в імпорті окремих товарів

Практичне застосування

Цей проект може бути корисним для:

Аналітиків ринку та економістів
Підприємств, що займаються зовнішньоекономічною діяльністю
Державних установ для моніторингу торговельних потоків
Дослідників у галузі міжнародної економіки та логістики
Трейдерів та імпортерів/експортерів для аналізу ринкових тенденцій

Опис Python коду для отримання даних міжнародної торгівлі

Загальний опис

Цей код створено для автоматичного отримання даних про міжнародну торгівлю України з використанням UN Comtrade API. Програма дозволяє збирати детальну інформацію про імпорт товарів за визначеним товарним кодом та зберігати ці дані у форматі JSON для подальшого аналізу.

Імпорт бібліотек

import pandas as pd               # для обробки табличних даних
import matplotlib.pyplot as plt   # для візуалізації даних
import numpy as np                # для числових обчислень
import comtradeapicall           # для взаємодії з UN Comtrade API
import time                      # для вимірювання часу виконання
import json                      # для роботи з JSON форматом
from datetime import datetime    # для роботи з датами

Основна функція

get_tariff_line_data() - функція для отримання тарифних даних з API UN Comtrade.

Параметри функції:

comtradeapicall - об'єкт для взаємодії з API
subscription_key - ключ підписки для доступу до API
period_string - рядок з періодами у форматі YYYYMM, розділені комами
Commodity_code - код товару за класифікацією HS

Робота функції:

Вимірювання часу виконання:

start_time = time.time()
# Виконання запиту
end_time = time.time()
execution_time = end_time - start_time

Виконання запиту до API:
```
panDForig = comtradeapicall._getTarifflineData(...)
```
- Вказується тип даних (typeCode='C')
- Частота даних (щомісячні, freqCode='M')
- Використовується класифікація Harmonized System (clCode='HS')
- Запитується інформація для України (код 804, reporterCode=804)
- Вказується специфічний товарний код
- Фільтрується за напрямком торговельного потоку (імпорт, flowCode='M')
- Запитується формат виведення JSON
- Включаються описи для кращого розуміння даних

Підготовка результатів:

results = {
    'commodity_code': Commodity_code,
    'total_rows': len(panDForig),
    'execution_time': execution_time,
    'timestamp': datetime.now().strftime("%Y-%m-%d %H:%M:%S")
}

Збереження даних у JSON-файл:
```
output_filename = f'tariff_data_{Commodity_code}_{datetime.now().strftime("%Y%m%d_%H%M%S")}.json'

with open(output_filename, 'w', encoding='utf-8') as f:
    json.dump({
        'metadata': results,
        'data': data_for_json
    }, f, ensure_ascii=False, indent=4)
```
- Файл іменується з використанням коду товару та часової мітки
- Дані зберігаються з Unicode символами (для підтримки різних мов)
- Використовується відступ для зручності читання
Виведення інформації в консоль для контролю процесу.

Виклик функції та підготовка даних

Ініціалізація змінних:

subscription_key = 'ede51c36a7db4b639bf9f220416e0f1f'  # ключ підписки
Commodity_code = '310520'  # код товару (мінеральні/хімічні добрива)
panDForig = pd.DataFrame()  # порожній DataFrame для результатів

Підготовка часових періодів:

period_start = '2019-01-01'  # початок періоду
period_end = '2025-04-01'    # кінець періоду
periods = pd.date_range(period_start, period_end, freq='MS').strftime("%Y%m").tolist()

Створюється діапазон дат з місячним інтервалом
Дати форматуються у вигляді YYYYMM та конвертуються у список

Об'єднання періодів у рядок:

delim = ","
temp = list(map(str, periods))
period_string = delim.join(temp)

Перетворення списку періодів у рядок з комами для передачі в API

Виклик функції:

panDForig = get_tariff_line_data(comtradeapicall, subscription_key, period_string, Commodity_code)

Особливості та рекомендації

Оптимізація запитів: Код розбиває запити на періоди, щоб уникнути тайм-аутів при роботі з великими обсягами даних.
Безпека ключа: У реальних проектах рекомендується зберігати ключ підписки в захищеному місці (наприклад, в змінних середовища).
Масштабованість: Код можна легко модифікувати для аналізу різних товарних кодів або інших параметрів торгівлі.
Моніторинг продуктивності: Вимірювання часу виконання дозволяє оптимізувати запити при роботі з великими наборами даних.
Резервне копіювання: Збереження результатів у файли з часовими мітками створює історію запитів та забезпечує надійне збереження даних.

pip install comtradeapicall

import pandas as pd
import matplotlib.pyplot as plt
import numpy as np
import comtradeapicall
import time
import json
from datetime import datetime

def get_tariff_line_data(comtradeapicall, subscription_key, period_string, Commodity_code):
    # Початок вимірювання часу
    start_time = time.time()
    
    # Виконання запиту
    panDForig = comtradeapicall._getTarifflineData(
        subscription_key, 
        typeCode='C',           # тип даних 
        freqCode='M',           # щомісячні дані
        clCode='HS',            # класифікація Harmonized System
        period=period_string,   # часовий період
        reporterCode=804,       # код України в UN Comtrade (804)
        cmdCode=Commodity_code, # специфічний товарний код
        flowCode='M',           # напрямок торговельного потоку  !!! Іморт має бути
        partnerCode=None, 
        partner2Code=None, 
        customsCode=None, 
        motCode=None, 
        maxRecords=None,
        format_output='JSON',   # формат JSON
        #format_output='CSV',   # формат JSON
        
        countOnly=None, 
        includeDesc=True        # включати описи
    )
    
    # Завершення вимірювання часу
    end_time = time.time()
    execution_time = end_time - start_time
    
    # Підготовка результатів
    results = {
        'commodity_code': Commodity_code,
        'total_rows': len(panDForig),
        'execution_time': execution_time,
        'timestamp': datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    }
    
    # Конвертація DataFrame в список словників для серіалізації
    data_for_json = panDForig.to_dict(orient='records')
    
    # Запис результатів у файл
    output_filename = f'tariff_data_{Commodity_code}_{datetime.now().strftime("%Y%m%d_%H%M%S")}.json'
    
    with open(output_filename, 'w', encoding='utf-8') as f:
        json.dump({
            'metadata': results,
            'data': data_for_json
        }, f, ensure_ascii=False, indent=4)
    
    # Виведення інформації в консоль
    print(f"Результати для товарного коду {Commodity_code}:")
    print(f"Кількість рядків: {results['total_rows']}")
    print(f"Час виконання: {execution_time:.2f} сек")
    print(f"Файл збережено: {output_filename}")
    
    return panDForig


# Викликати для отримання тарифних даних API до кадру даних, максимум до 250 тис. записів, необхідний ключ безкоштовної/преміум-підписки
# Цей приклад: імпорт призначеного commodity_code 
subscription_key = 'ede51c36a7db4b639bf9f220416e0f1f'
Commodity_code = '310520' 


# create an Empty DataFrame object
panDForig = pd.DataFrame()
# A list of periods (this is for monthly sets), this is to optimize the API calls and avoid timeout
period_start = '2019-01-01'
period_end = '2025-04-01'
periods = pd.date_range(period_start,period_end,
              freq='MS').strftime("%Y%m").tolist()


# convert periods list into string with comma delimiter
delim = ","
temp = list(map(str, periods))
period_string = delim.join(temp)
print(period_string)


# Приклад виклику функції
panDForig = get_tariff_line_data(comtradeapicall, subscription_key, period_string, Commodity_code)