| Name | comtradeapicall JSON |
| Version |
1.2.1
JSON |
| download |
| home_page | None |
| Summary | A package to call UN Comtrade APIs |
| upload_time | 2024-04-19 14:39:06 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# UN Comtrade API Package
This package simplifies calling [APIs of UN Comtrade](https://comtradedeveloper.un.org) to extract and download data
(and much more).
## Details
[UN Comtrade](https://comtrade.un.org) provides free and premium APIs to extract and download data/metadata, however
it is quite a learning curve to understand all of APIs end-points and parameters. This package simplifies it by
calling a single python function with the appropriate parameters. Learn more about UN Comtrade at the [UN Comtrade Docs](https://uncomtrade.org/docs).
This project is intended to be deployed at [The Python Package Index](https://pypi.org/project/comtradeapicall/), therefore the structure of
folders follows the suggested layout from [Packaging Python Project](https://packaging.python.org/en/latest/tutorials/packaging-projects/). The main scripts are located at **/src/comtradeapicall/**. And the folder **tests** contains the example scripts how to install and use the package.
## Prerequisites
This package assumes using Python 3.7 and the expected package dependencies are listed in the "requirements.txt" file
for PIP, you need to run the following command to get dependencies:
```
pip install -r requirements.txt
```
## Installing the package (from PyPi)
The package has been deployed to the PyPi and it can be install using pip command below:
```
pip install comtradeapicall
```
## Components
- **Get/Preview:** Model class to extract the data into pandas data frame
- previewFinalData(**SelectionCriteria**, **query_option**) : return data frame containing final trade data (limited to 500 records)
- previewTarifflineData(**SelectionCriteria**, **query_option**) : return data frame containing tariff line data (limited to 500
records)
- getFinalData(**subscription_key**, **SelectionCriteria**, **query_option**) : return data frame containing final
trade data (limited to 250K records)
- getTarifflineData(**subscription_key**, **SelectionCriteria**, **query_option**) : return data frame containing
tariff line data (limited to 250K records)
- Alternative functions of _previewFinalData, _previewTarifflineData, _getFinalData, _getTarifflineData returns the
same data frame, respectively, with query optimization by calling multiple APIs based on the periods (instead of
single API call)
- **DataAvailability:** Model class to extract data availability
- _getFinalDataAvailability(**SelectionCriteria**) : return data frame containing final data
availability - no subscription key
- getFinalDataAvailability(**subscription_key**, **SelectionCriteria**) : return data frame containing final data
availability
- _getTarifflineDataAvailability(**SelectionCriteria**) : return data frame containing tariff
line
data
availability - no subscription key
- getTarifflineDataAvailability(**subscription_key**, **SelectionCriteria**) : return data frame containing tariff
line
data
availability
- getFinalDataBulkAvailability(**subscription_key**, **SelectionCriteria**, **[publishedDateFrom]**, **[publishedDateTo]**) : return data frame containing final bulk files data
availability
- getTarifflineDataBulkAvailability(**subscription_key**, **SelectionCriteria**, **[publishedDateFrom]**, **[publishedDateTo]**) : return data frame containing tariff
line bulk files
data
availability
- getLiveUpdate(**subscription_key**) : return data frame recent data releases
- **BulkDownload:** Model class to download the data files
- bulkDownloadFinalData(**subscription_key**, **directory**, **SelectionCriteria**, **decompress**, **[publishedDateFrom]**, **[publishedDateTo]**) : download/save
final data files to specified folder
- bulkDownloadFinalClassicData(**subscription_key**, **directory**, **SelectionCriteria**, **decompress**, **[publishedDateFrom]**, **[publishedDateTo]**) : download/save
final classic data files to specified folder
- bulkDownloadTarifflineData(**subscription_key**, **directory**, **SelectionCriteria**, **decompress**, **[publishedDateFrom]**, **[publishedDateTo]**) : download
/save tariff line data files to specified folder
- **Async:** Model class to extract the data asynchronously (limited to 2.5M records) with email notification
- submitAsyncFinalDataRequest(**subscription_key**, **SelectionCriteria**, **query_option**) : submit a final data job
- submitAsyncTarifflineDataRequest(**subscription_key**, **SelectionCriteria**, **query_option**) : submit a tariff line data job
- checkAsyncDataRequest(**subscription_key**, **[batchId]**) : check status of submitted job
- downloadAsyncFinalDataRequest(**subscription_key**, **directory**, **SelectionCriteria**, **query_option**) : submit, wait and download the resulting final file
- downloadAsyncTarifflineDataRequest(**subscription_key**, **directory**, **SelectionCriteria**, **query_option**) : submit, wait and download the resulting tariff line file
- **Metadata:** Model class to extract metadata and publication notes
- _getMetadata(**SelectionCriteria**, **showHistory**) : return data frame with metadata and publication notes - no subscription key
- getMetadata(**subscription_key**, **SelectionCriteria**, **showHistory**) : return data frame with metadata and publication notes
- listReference(**[category]**) : return data frame containing list of references
- getReference(**category**) : return data frame with the contents of specific references
- **SUV:** Model class to extract data on Standard Unit Values (SUV) and their ranges
- getSUV(**subscription_key**, **SelectionCriteria**, **[qtyUnitCode]**) : return data frame with SUV data
- **AIS:** Model class to extract experimental trade data generated from AIS (ships tracking movement). See [Cerdeiro, Komaromi, Liu and Saeed (2020)](https://www.imf.org/en/Publications/WP/Issues/2020/05/14/World-Seaborne-Trade-in-Real-Time-A-Proof-of-Concept-for-Building-AIS-based-Nowcasts-from-49393). *When consuming the data, users should understand its limitation.*
- getAIS(**subscription_key**, **AISSelectionCriteria**, **[vesselTypeCode]**) : return data frame with AIS trade data
See differences between final and tariff line data at the [Docs](https://uncomtrade.org/docs/what-is-tariffline-data/)
## Selection Criteria
- typeCode(str) : Product type. Goods (C) or Services (S)
- freqCode(str) : The time interval at which observations occur. Annual (A) or Monthly (M)
- clCode(str) : Indicates the product classification used and which version (HS, SITC)
- period(str) : Combination of year and month (for monthly), year for (annual)
- reporterCode(str) : The country or geographic area to which the measured statistical phenomenon relates
- cmdCode(str) : Product code in conjunction with classification code
- flowCode(str) : Trade flow or sub-flow (exports, re-exports, imports, re-imports, etc.)
- partnerCode(str) : The primary partner country or geographic area for the respective trade flow
- partner2Code(str) : A secondary partner country or geographic area for the respective trade flow
- customsCode(str) : Customs or statistical procedure
- motCode(str) : The mode of transport used when goods enter or leave the economic territory of a country
## Query Options
- maxRecords(int) : Limit number of returned records
- format_output(str) : The output format. CSV or JSON
- aggregateBy(str) : Option for aggregating the query
- breakdownMode(str) : Option to select the classic (trade by partner/product) or plus (extended breakdown) mode
- countOnly(bool) : Return the actual number of records if set to True
- includeDesc(bool) : Option to include the description or not
## AIS Selection Criteria
- typeCode(str) : Product type. Only Goods (C)
- freqCode(str) : The time interval at which observations occur. Daily (D)
- datefrom(str) and dateto(str) : Date(s) of observation - ASCII format
- countryareaCode(str) : The country or geographic area to which the measured statistical phenomenon relates. Use *getReference('ais:countriesareas')* for the complete list.
- vesselTypeCode(str) : The high level categorization of vessels transporting the goods. Use *getReference('ais:vesseltypes')* for the complete list.
- flowCode(str) : Trade flow (exports, imports)
## Proxy Server
- proxy_url(str) : All functions that call the API support the proxy server. Use the parameter proxy_url.
## Examples of python usage
- Extract Australia imports of commodity code 91 in classic mode in May 2022
``` python
mydf = comtradeapicall.previewFinalData(typeCode='C', freqCode='M', clCode='HS', period='202205',
reporterCode='36', cmdCode='91', flowCode='M', partnerCode=None,
partner2Code=None,
customsCode=None, motCode=None, maxRecords=500, format_output='JSON',
aggregateBy=None, breakdownMode='classic', countOnly=None, includeDesc=True)
```
- Extract Australia tariff line imports of commodity code started with 90 and 91 from Indonesia in May 2022
``` python
mydf = comtradeapicall.previewTarifflineData(typeCode='C', freqCode='M', clCode='HS', period='202205',
reporterCode='36', cmdCode='91,90', flowCode='M', partnerCode=36,
partner2Code=None,
customsCode=None, motCode=None, maxRecords=500, format_output='JSON',
countOnly=None, includeDesc=True)
```
- Extract Australia imports of commodity codes 90 and 91 from all partners in classic mode in May 2022
``` python
mydf = comtradeapicall.getFinalData(subscription_key, typeCode='C', freqCode='M', clCode='HS', period='202205',
reporterCode='36', cmdCode='91,90', flowCode='M', partnerCode=None,
partner2Code=None,
customsCode=None, motCode=None, maxRecords=2500, format_output='JSON',
aggregateBy=None, breakdownMode='classic', countOnly=None, includeDesc=True)
```
- Extract Australia tariff line imports of commodity code started with 90 and 91 from Indonesia in May 2022
``` python
mydf = comtradeapicall.getTarifflineData(subscription_key, typeCode='C', freqCode='M', clCode='HS', period='202205',
reporterCode='36', cmdCode='91,90', flowCode='M', partnerCode=36,
partner2Code=None,
customsCode=None, motCode=None, maxRecords=2500, format_output='JSON',
countOnly=None, includeDesc=True)
```
- Download monthly France final data of Jan-2000
``` python
comtradeapicall.bulkDownloadFinalFile(subscription_key, directory, typeCode='C', freqCode='M', clCode='HS',
period='200001', reporterCode=251, decompress=True)
```
- Download monthly France tariff line data of Jan-March 2000
``` python
comtradeapicall.bulkDownloadTarifflineFile(subscription_key, directory, typeCode='C', freqCode='M', clCode='HS',
period='200001,200002,200003', reporterCode=504, decompress=True)
```
- Download annual Morocco tariff line data of 2010
``` python
comtradeapicall.bulkDownloadTarifflineFile(subscription_key, directory, typeCode='C', freqCode='A', clCode='HS',
period='2010', reporterCode=504, decompress=True)
```
- Download all final annual data in HS classification released yesterday
``` python
yesterday = date.today() - timedelta(days=1)
comtradeapicall.bulkDownloadTarifflineFile(subscription_key, directory, typeCode='C', freqCode='A', clCode='HS',
period=None, reporterCode=None, decompress=True,
publishedDateFrom=yesterday, publishedDateTo=None)
```
- Show the recent releases
``` python
mydf = comtradeapicall.getLiveUpdate(subscription_key)
```
- Extract final data availability in 2021
``` python
mydf = comtradeapicall.getFinalDataAvailability(subscription_key, typeCode='C', freqCode='A', clCode='HS',
period='2021', reporterCode=None)
```
- Extract tariff line data availability in June 2022
``` python
mydf = comtradeapicall.getTarifflineDataAvailability(subscription_key, typeCode='C', freqCode='M', clCode='HS',
period='202206', reporterCode=None)
```
- Extract final bulk files data availability in 2021 for the SITC Rev.1 classification
``` python
mydf = comtradeapicall.getFinalDataBulkAvailability(subscription_key, typeCode='C', freqCode='A', clCode='S1',
period='2021', reporterCode=None)
```
- Extract tariff line bulk files data availability in June 2022
``` python
mydf = comtradeapicall.getTarifflineDataBulkAvailability(subscription_key, typeCode='C', freqCode='M', clCode='HS',
period='202206', reporterCode=None)
```
- List data availabity from last week for reference year 2021
``` python
mydf = comtradeapicall.getFinalDataAvailability(subscription_key, typeCode='C', freqCode='A', clCode='HS',period='2021', reporterCode=None, publishedDateFrom=lastweek, publishedDateTo=None)
```
- List tariffline data availabity from last week for reference period June 2022
``` python
mydf = comtradeapicall.getTarifflineDataAvailability(subscription_key, typeCode='C', freqCode='M',
clCode='HS',
period='202206', reporterCode=None, publishedDateFrom=lastweek, publishedDateTo=None)
```
- List bulk data availability for SITC Rev.1 for reference year 2021 released since last week
``` python
mydf = comtradeapicall.getFinalDataBulkAvailability(subscription_key, typeCode='C', freqCode='A',
clCode='S1',
period='2021', reporterCode=None, publishedDateFrom=lastweek, publishedDateTo=None)
```
- List bulk tariffline data availability from last week for reference period June 2022
``` python
mydf = comtradeapicall.getTarifflineDataBulkAvailability(subscription_key, typeCode='C', freqCode='M',
clCode='HS',
period='202206', reporterCode=None, publishedDateFrom=lastweek, publishedDateTo=None)
```
- Obtain all metadata and publication notes for May 2022
``` python
mydf = comtradeapicall.getMetadata(subscription_key, typeCode='C', freqCode='M', clCode='HS', period='202205',
reporterCode=None, showHistory=True)
```
- Submit asynchronous final data request
``` python
myJson = comtradeapicall.submitAsyncFinalDataRequest(subscription_key, typeCode='C', freqCode='M', clCode='HS',
period='202205',
reporterCode='36', cmdCode='91,90', flowCode='M', partnerCode=None,
partner2Code=None,
customsCode=None, motCode=None, aggregateBy=None, breakdownMode='classic')
print("requestID: ",myJson['requestId'])
```
- Submit asynchronous tariff line data request
``` python
myJson = comtradeapicall.submitAsyncTarifflineDataRequest(subscription_key, typeCode='C', freqCode='M',
clCode='HS',
period='202205',
reporterCode=None, cmdCode='91,90', flowCode='M', partnerCode=None,
partner2Code=None,
customsCode=None, motCode=None)
print("requestID: ",myJson['requestId'])
```
- Check status of asynchronous job
``` python
mydf = comtradeapicall.checkAsyncDataRequest(subscription_key,
batchId ='2f92dd59-9763-474c-b27c-4af9ce16d454' )
```
- Submit final data asynchronous job and download the resulting file
``` python
comtradeapicall.downloadAsyncFinalDataRequest(subscription_key, directory, typeCode='C', freqCode='M',
clCode='HS', period='202209', reporterCode=None, cmdCode='91,90',
flowCode='M', partnerCode=None, partner2Code=None,
customsCode=None, motCode=None)
```
- Submit tariffline data asynchronous job and download the resulting file
``` python
comtradeapicall.downloadAsyncTarifflineDataRequest(subscription_key, directory, typeCode='C', freqCode='M',
clCode='HS', period='202209', reporterCode=None, cmdCode='91,90',
flowCode='M', partnerCode=None, partner2Code=None,
customsCode=None, motCode=None)
```
- View list of reference tables
``` python
mydf = comtradeapicall.listReference()
mydf = comtradeapicall.listReference('cmd:B5')
```
- Download specific reference
``` python
mydf = comtradeapicall.getReference('reporter')
mydf = comtradeapicall.getReference('partner')
```
- Convert country/area ISO3 to Comtrade code
``` python
country_code = comtradeapicall.convertCountryIso3ToCode('USA,FRA,CHE,ITA')
```
- Get the Standard unit value (qtyUnitCode 8 [kg]) for commodity 010391 in 2022
``` python
mydf = comtradeapicall.getSUV(subscription_key, period='2022', cmdCode='010391', flowCode=None, qtyUnitCode=8)
```
- Get number of port calls and trade volume estimates derrived from AIS data for Australia between 1 and 8 February 2023 with vessel types bulk and container.
``` python
mydf = comtradeapicall.getAIS(subscription_key, countryareaCode=36, vesselTypeCode='1,2', dateFrom='2023-02-01', dateTo='2023-02-08')
```
- Tests folder contain more examples including calculation of unit value
## Downloaded file name convention
The naming convention follows the following : "COMTRADE-\<DATA>-\<TYPE>\<FREQ>\<COUNTRY CODE>\<YEAR\[
-MONTH\]>\<CLASSIFICATION CODE>\[\<RELEASE DATE\>\]"
As examples:
- Final merchandise trade data from Morocco (code 504) in March 2000 released on 3 Jan 2023 coded using H1
classification:
- *COMTRADE-FINAL-CM504200003H1[2023-01-03]*
- Tariffline merchandise trade from Morocco (code 504) in March 2000 released on 3 Jan 2023 coded using H1 classification:
- *COMTRADE-TARIFFLINE-CM504200003H1[2023-01-03]*
Note: Async download retains the original batch id
Raw data
{
"_id": null,
"home_page": null,
"name": "comtradeapicall",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "untradestats <untradestats@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a4/8f/24ce018983618cf36982b178eca5071bfb99bd5dcf36f8e099b495608140/comtradeapicall-1.2.1.tar.gz",
"platform": null,
"description": "# UN Comtrade API Package\r\nThis package simplifies calling [APIs of UN Comtrade](https://comtradedeveloper.un.org) to extract and download data\r\n (and much more). \r\n\r\n## Details\r\n[UN Comtrade](https://comtrade.un.org) provides free and premium APIs to extract and download data/metadata, however\r\n it is quite a learning curve to understand all of APIs end-points and parameters. This package simplifies it by\r\n calling a single python function with the appropriate parameters. Learn more about UN Comtrade at the [UN Comtrade Docs](https://uncomtrade.org/docs).\r\n\r\nThis project is intended to be deployed at [The Python Package Index](https://pypi.org/project/comtradeapicall/), therefore the structure of\r\n folders follows the suggested layout from [Packaging Python Project](https://packaging.python.org/en/latest/tutorials/packaging-projects/). The main scripts are located at **/src/comtradeapicall/**. And the folder **tests** contains the example scripts how to install and use the package.\r\n \r\n ## Prerequisites\r\nThis package assumes using Python 3.7 and the expected package dependencies are listed in the \"requirements.txt\" file\r\n for PIP, you need to run the following command to get dependencies:\r\n```\r\npip install -r requirements.txt\r\n```\r\n\r\n## Installing the package (from PyPi)\r\nThe package has been deployed to the PyPi and it can be install using pip command below:\r\n```\r\npip install comtradeapicall\r\n```\r\n\r\n## Components\r\n- **Get/Preview:** Model class to extract the data into pandas data frame\r\n - previewFinalData(**SelectionCriteria**, **query_option**) : return data frame containing final trade data (limited to 500 records)\r\n - previewTarifflineData(**SelectionCriteria**, **query_option**) : return data frame containing tariff line data (limited to 500\r\n records)\r\n - getFinalData(**subscription_key**, **SelectionCriteria**, **query_option**) : return data frame containing final\r\n trade data (limited to 250K records)\r\n - getTarifflineData(**subscription_key**, **SelectionCriteria**, **query_option**) : return data frame containing\r\n tariff line data (limited to 250K records)\r\n - Alternative functions of _previewFinalData, _previewTarifflineData, _getFinalData, _getTarifflineData returns the\r\n same data frame, respectively, with query optimization by calling multiple APIs based on the periods (instead of\r\n single API call)\r\n \r\n- **DataAvailability:** Model class to extract data availability\r\n - _getFinalDataAvailability(**SelectionCriteria**) : return data frame containing final data\r\n availability - no subscription key\r\n - getFinalDataAvailability(**subscription_key**, **SelectionCriteria**) : return data frame containing final data\r\n availability\r\n - _getTarifflineDataAvailability(**SelectionCriteria**) : return data frame containing tariff\r\n line\r\n data\r\n availability - no subscription key\r\n - getTarifflineDataAvailability(**subscription_key**, **SelectionCriteria**) : return data frame containing tariff\r\n line\r\n data\r\n availability\r\n - getFinalDataBulkAvailability(**subscription_key**, **SelectionCriteria**, **[publishedDateFrom]**, **[publishedDateTo]**) : return data frame containing final bulk files data\r\n availability\r\n - getTarifflineDataBulkAvailability(**subscription_key**, **SelectionCriteria**, **[publishedDateFrom]**, **[publishedDateTo]**) : return data frame containing tariff\r\n line bulk files \r\n data\r\n availability\r\n - getLiveUpdate(**subscription_key**) : return data frame recent data releases\r\n \r\n- **BulkDownload:** Model class to download the data files\r\n - bulkDownloadFinalData(**subscription_key**, **directory**, **SelectionCriteria**, **decompress**, **[publishedDateFrom]**, **[publishedDateTo]**) : download/save\r\n final data files to specified folder\r\n - bulkDownloadFinalClassicData(**subscription_key**, **directory**, **SelectionCriteria**, **decompress**, **[publishedDateFrom]**, **[publishedDateTo]**) : download/save\r\n final classic data files to specified folder \r\n - bulkDownloadTarifflineData(**subscription_key**, **directory**, **SelectionCriteria**, **decompress**, **[publishedDateFrom]**, **[publishedDateTo]**) : download\r\n /save tariff line data files to specified folder\r\n\r\n- **Async:** Model class to extract the data asynchronously (limited to 2.5M records) with email notification\r\n - submitAsyncFinalDataRequest(**subscription_key**, **SelectionCriteria**, **query_option**) : submit a final data job\r\n - submitAsyncTarifflineDataRequest(**subscription_key**, **SelectionCriteria**, **query_option**) : submit a tariff line data job\r\n - checkAsyncDataRequest(**subscription_key**, **[batchId]**) : check status of submitted job\r\n - downloadAsyncFinalDataRequest(**subscription_key**, **directory**, **SelectionCriteria**, **query_option**) : submit, wait and download the resulting final file\r\n - downloadAsyncTarifflineDataRequest(**subscription_key**, **directory**, **SelectionCriteria**, **query_option**) : submit, wait and download the resulting tariff line file\r\n \r\n- **Metadata:** Model class to extract metadata and publication notes\r\n - _getMetadata(**SelectionCriteria**, **showHistory**) : return data frame with metadata and publication notes - no subscription key\r\n - getMetadata(**subscription_key**, **SelectionCriteria**, **showHistory**) : return data frame with metadata and publication notes\r\n - listReference(**[category]**) : return data frame containing list of references\r\n - getReference(**category**) : return data frame with the contents of specific references\r\n\r\n- **SUV:** Model class to extract data on Standard Unit Values (SUV) and their ranges\r\n - getSUV(**subscription_key**, **SelectionCriteria**, **[qtyUnitCode]**) : return data frame with SUV data\r\n\r\n- **AIS:** Model class to extract experimental trade data generated from AIS (ships tracking movement). See [Cerdeiro, Komaromi, Liu and Saeed (2020)](https://www.imf.org/en/Publications/WP/Issues/2020/05/14/World-Seaborne-Trade-in-Real-Time-A-Proof-of-Concept-for-Building-AIS-based-Nowcasts-from-49393). *When consuming the data, users should understand its limitation.* \r\n - getAIS(**subscription_key**, **AISSelectionCriteria**, **[vesselTypeCode]**) : return data frame with AIS trade data\r\n\r\nSee differences between final and tariff line data at the [Docs](https://uncomtrade.org/docs/what-is-tariffline-data/)\r\n \r\n## Selection Criteria\r\n- typeCode(str) : Product type. Goods (C) or Services (S)\r\n- freqCode(str) : The time interval at which observations occur. Annual (A) or Monthly (M)\r\n- clCode(str) : Indicates the product classification used and which version (HS, SITC)\r\n- period(str) : Combination of year and month (for monthly), year for (annual)\r\n- reporterCode(str) : The country or geographic area to which the measured statistical phenomenon relates\r\n- cmdCode(str) : Product code in conjunction with classification code\r\n- flowCode(str) : Trade flow or sub-flow (exports, re-exports, imports, re-imports, etc.)\r\n- partnerCode(str) : The primary partner country or geographic area for the respective trade flow\r\n- partner2Code(str) : A secondary partner country or geographic area for the respective trade flow\r\n- customsCode(str) : Customs or statistical procedure\r\n- motCode(str) : The mode of transport used when goods enter or leave the economic territory of a country\r\n\r\n## Query Options\r\n- maxRecords(int) : Limit number of returned records\r\n- format_output(str) : The output format. CSV or JSON \r\n- aggregateBy(str) : Option for aggregating the query \r\n- breakdownMode(str) : Option to select the classic (trade by partner/product) or plus (extended breakdown) mode\r\n- countOnly(bool) : Return the actual number of records if set to True \r\n- includeDesc(bool) : Option to include the description or not\r\n\r\n## AIS Selection Criteria\r\n- typeCode(str) : Product type. Only Goods (C)\r\n- freqCode(str) : The time interval at which observations occur. Daily (D)\r\n- datefrom(str) and dateto(str) : Date(s) of observation - ASCII format\r\n- countryareaCode(str) : The country or geographic area to which the measured statistical phenomenon relates. Use *getReference('ais:countriesareas')* for the complete list.\r\n- vesselTypeCode(str) : The high level categorization of vessels transporting the goods. Use *getReference('ais:vesseltypes')* for the complete list.\r\n- flowCode(str) : Trade flow (exports, imports)\r\n\r\n## Proxy Server\r\n- proxy_url(str) : All functions that call the API support the proxy server. Use the parameter proxy_url.\r\n\r\n \r\n## Examples of python usage\r\n- Extract Australia imports of commodity code 91 in classic mode in May 2022\r\n``` python\r\nmydf = comtradeapicall.previewFinalData(typeCode='C', freqCode='M', clCode='HS', period='202205',\r\n reporterCode='36', cmdCode='91', flowCode='M', partnerCode=None,\r\n partner2Code=None,\r\n customsCode=None, motCode=None, maxRecords=500, format_output='JSON',\r\n aggregateBy=None, breakdownMode='classic', countOnly=None, includeDesc=True)\r\n``` \r\n- Extract Australia tariff line imports of commodity code started with 90 and 91 from Indonesia in May 2022\r\n``` python\r\nmydf = comtradeapicall.previewTarifflineData(typeCode='C', freqCode='M', clCode='HS', period='202205',\r\n reporterCode='36', cmdCode='91,90', flowCode='M', partnerCode=36,\r\n partner2Code=None,\r\n customsCode=None, motCode=None, maxRecords=500, format_output='JSON',\r\n countOnly=None, includeDesc=True)\r\n``` \r\n- Extract Australia imports of commodity codes 90 and 91 from all partners in classic mode in May 2022\r\n``` python\r\nmydf = comtradeapicall.getFinalData(subscription_key, typeCode='C', freqCode='M', clCode='HS', period='202205',\r\n reporterCode='36', cmdCode='91,90', flowCode='M', partnerCode=None,\r\n partner2Code=None,\r\n customsCode=None, motCode=None, maxRecords=2500, format_output='JSON',\r\n aggregateBy=None, breakdownMode='classic', countOnly=None, includeDesc=True)\r\n``` \r\n- Extract Australia tariff line imports of commodity code started with 90 and 91 from Indonesia in May 2022\r\n``` python\r\nmydf = comtradeapicall.getTarifflineData(subscription_key, typeCode='C', freqCode='M', clCode='HS', period='202205',\r\n reporterCode='36', cmdCode='91,90', flowCode='M', partnerCode=36,\r\n partner2Code=None,\r\n customsCode=None, motCode=None, maxRecords=2500, format_output='JSON',\r\n countOnly=None, includeDesc=True)\r\n``` \r\n- Download monthly France final data of Jan-2000\r\n``` python\r\ncomtradeapicall.bulkDownloadFinalFile(subscription_key, directory, typeCode='C', freqCode='M', clCode='HS',\r\n period='200001', reporterCode=251, decompress=True)\r\n``` \r\n- Download monthly France tariff line data of Jan-March 2000\r\n``` python\r\ncomtradeapicall.bulkDownloadTarifflineFile(subscription_key, directory, typeCode='C', freqCode='M', clCode='HS',\r\n period='200001,200002,200003', reporterCode=504, decompress=True)\r\n``` \r\n- Download annual Morocco tariff line data of 2010\r\n``` python\r\ncomtradeapicall.bulkDownloadTarifflineFile(subscription_key, directory, typeCode='C', freqCode='A', clCode='HS',\r\n period='2010', reporterCode=504, decompress=True)\r\n``` \r\n- Download all final annual data in HS classification released yesterday\r\n``` python\r\nyesterday = date.today() - timedelta(days=1)\r\ncomtradeapicall.bulkDownloadTarifflineFile(subscription_key, directory, typeCode='C', freqCode='A', clCode='HS',\r\n period=None, reporterCode=None, decompress=True,\r\n publishedDateFrom=yesterday, publishedDateTo=None)\r\n``` \r\n- Show the recent releases\r\n``` python\r\nmydf = comtradeapicall.getLiveUpdate(subscription_key)\r\n``` \r\n- Extract final data availability in 2021\r\n``` python\r\nmydf = comtradeapicall.getFinalDataAvailability(subscription_key, typeCode='C', freqCode='A', clCode='HS',\r\n period='2021', reporterCode=None)\r\n``` \r\n- Extract tariff line data availability in June 2022\r\n``` python\r\nmydf = comtradeapicall.getTarifflineDataAvailability(subscription_key, typeCode='C', freqCode='M', clCode='HS',\r\n period='202206', reporterCode=None)\r\n``` \r\n- Extract final bulk files data availability in 2021 for the SITC Rev.1 classification\r\n``` python\r\nmydf = comtradeapicall.getFinalDataBulkAvailability(subscription_key, typeCode='C', freqCode='A', clCode='S1',\r\n period='2021', reporterCode=None)\r\n``` \r\n- Extract tariff line bulk files data availability in June 2022\r\n``` python\r\nmydf = comtradeapicall.getTarifflineDataBulkAvailability(subscription_key, typeCode='C', freqCode='M', clCode='HS',\r\n period='202206', reporterCode=None)\r\n``` \r\n- List data availabity from last week for reference year 2021\r\n``` python\r\nmydf = comtradeapicall.getFinalDataAvailability(subscription_key, typeCode='C', freqCode='A', clCode='HS',period='2021', reporterCode=None, publishedDateFrom=lastweek, publishedDateTo=None)\r\n``` \r\n- List tariffline data availabity from last week for reference period June 2022\r\n``` python\r\nmydf = comtradeapicall.getTarifflineDataAvailability(subscription_key, typeCode='C', freqCode='M',\r\n clCode='HS',\r\n period='202206', reporterCode=None, publishedDateFrom=lastweek, publishedDateTo=None)\r\n``` \r\n- List bulk data availability for SITC Rev.1 for reference year 2021 released since last week\r\n``` python\r\nmydf = comtradeapicall.getFinalDataBulkAvailability(subscription_key, typeCode='C', freqCode='A',\r\n clCode='S1',\r\n period='2021', reporterCode=None, publishedDateFrom=lastweek, publishedDateTo=None)\r\n``` \r\n- List bulk tariffline data availability from last week for reference period June 2022\r\n``` python\r\nmydf = comtradeapicall.getTarifflineDataBulkAvailability(subscription_key, typeCode='C', freqCode='M',\r\n clCode='HS',\r\n period='202206', reporterCode=None, publishedDateFrom=lastweek, publishedDateTo=None)\r\n\r\n``` \r\n- Obtain all metadata and publication notes for May 2022\r\n``` python\r\nmydf = comtradeapicall.getMetadata(subscription_key, typeCode='C', freqCode='M', clCode='HS', period='202205',\r\n reporterCode=None, showHistory=True)\r\n``` \r\n- Submit asynchronous final data request\r\n``` python\r\nmyJson = comtradeapicall.submitAsyncFinalDataRequest(subscription_key, typeCode='C', freqCode='M', clCode='HS',\r\n period='202205',\r\n reporterCode='36', cmdCode='91,90', flowCode='M', partnerCode=None,\r\n partner2Code=None,\r\n customsCode=None, motCode=None, aggregateBy=None, breakdownMode='classic')\r\nprint(\"requestID: \",myJson['requestId'])\r\n``` \r\n- Submit asynchronous tariff line data request\r\n``` python\r\nmyJson = comtradeapicall.submitAsyncTarifflineDataRequest(subscription_key, typeCode='C', freqCode='M',\r\n clCode='HS',\r\n period='202205',\r\n reporterCode=None, cmdCode='91,90', flowCode='M', partnerCode=None,\r\n partner2Code=None,\r\n customsCode=None, motCode=None)\r\nprint(\"requestID: \",myJson['requestId'])\r\n``` \r\n- Check status of asynchronous job\r\n``` python\r\nmydf = comtradeapicall.checkAsyncDataRequest(subscription_key, \r\n batchId ='2f92dd59-9763-474c-b27c-4af9ce16d454' )\r\n``` \r\n- Submit final data asynchronous job and download the resulting file\r\n``` python\r\ncomtradeapicall.downloadAsyncFinalDataRequest(subscription_key, directory, typeCode='C', freqCode='M',\r\n clCode='HS', period='202209', reporterCode=None, cmdCode='91,90',\r\n flowCode='M', partnerCode=None, partner2Code=None,\r\n customsCode=None, motCode=None)\r\n``` \r\n- Submit tariffline data asynchronous job and download the resulting file\r\n``` python\r\ncomtradeapicall.downloadAsyncTarifflineDataRequest(subscription_key, directory, typeCode='C', freqCode='M',\r\n clCode='HS', period='202209', reporterCode=None, cmdCode='91,90',\r\n flowCode='M', partnerCode=None, partner2Code=None,\r\n customsCode=None, motCode=None)\r\n``` \r\n- View list of reference tables\r\n``` python\r\nmydf = comtradeapicall.listReference()\r\nmydf = comtradeapicall.listReference('cmd:B5')\r\n``` \r\n- Download specific reference\r\n``` python\r\nmydf = comtradeapicall.getReference('reporter')\r\nmydf = comtradeapicall.getReference('partner')\r\n``` \r\n- Convert country/area ISO3 to Comtrade code\r\n``` python\r\ncountry_code = comtradeapicall.convertCountryIso3ToCode('USA,FRA,CHE,ITA')\r\n``` \r\n- Get the Standard unit value (qtyUnitCode 8 [kg]) for commodity 010391 in 2022\r\n``` python\r\nmydf = comtradeapicall.getSUV(subscription_key, period='2022', cmdCode='010391', flowCode=None, qtyUnitCode=8)\r\n``` \r\n- Get number of port calls and trade volume estimates derrived from AIS data for Australia between 1 and 8 February 2023 with vessel types bulk and container.\r\n``` python\r\nmydf = comtradeapicall.getAIS(subscription_key, countryareaCode=36, vesselTypeCode='1,2', dateFrom='2023-02-01', dateTo='2023-02-08')\r\n``` \r\n- Tests folder contain more examples including calculation of unit value\r\n\r\n## Downloaded file name convention\r\nThe naming convention follows the following : \"COMTRADE-\\<DATA>-\\<TYPE>\\<FREQ>\\<COUNTRY CODE>\\<YEAR\\[\r\n-MONTH\\]>\\<CLASSIFICATION CODE>\\[\\<RELEASE DATE\\>\\]\"\r\n\r\nAs examples:\r\n- Final merchandise trade data from Morocco (code 504) in March 2000 released on 3 Jan 2023 coded using H1\r\n classification:\r\n - *COMTRADE-FINAL-CM504200003H1[2023-01-03]*\r\n- Tariffline merchandise trade from Morocco (code 504) in March 2000 released on 3 Jan 2023 coded using H1 classification: \r\n - *COMTRADE-TARIFFLINE-CM504200003H1[2023-01-03]*\r\n\r\nNote: Async download retains the original batch id\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A package to call UN Comtrade APIs",
"version": "1.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/uncomtrade/comtradeapicall/issues",
"Homepage": "https://github.com/uncomtrade/comtradeapicall"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ad20dbf7d3744f8233abdeaff0c7b7700c2d1b5e4b02eea0fddfab401d1524f8",
"md5": "78fdf570fd37e98c3ea7acc060f70553",
"sha256": "cc08ab2c48a2dfcd5b9adc3241f5a2559156660ba640868330408d67fb360518"
},
"downloads": -1,
"filename": "comtradeapicall-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "78fdf570fd37e98c3ea7acc060f70553",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19538,
"upload_time": "2024-04-19T14:39:04",
"upload_time_iso_8601": "2024-04-19T14:39:04.633779Z",
"url": "https://files.pythonhosted.org/packages/ad/20/dbf7d3744f8233abdeaff0c7b7700c2d1b5e4b02eea0fddfab401d1524f8/comtradeapicall-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a48f24ce018983618cf36982b178eca5071bfb99bd5dcf36f8e099b495608140",
"md5": "ac2476041706703500a09f0d2d93fdaa",
"sha256": "42f42294a90a4f83894c997cb29ac4801158296ceb9458b5f0196096c48d5815"
},
"downloads": -1,
"filename": "comtradeapicall-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "ac2476041706703500a09f0d2d93fdaa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15691,
"upload_time": "2024-04-19T14:39:06",
"upload_time_iso_8601": "2024-04-19T14:39:06.404999Z",
"url": "https://files.pythonhosted.org/packages/a4/8f/24ce018983618cf36982b178eca5071bfb99bd5dcf36f8e099b495608140/comtradeapicall-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-19 14:39:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "uncomtrade",
"github_project": "comtradeapicall",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "comtradeapicall"
}
