Python 說明文件

2019-10-08 更新

Python

以下文件將說明如何使用企業商務資料平台 Python API來存取資料。

安裝方式

僅需要利用 pip 安裝 kyc pip install kyc

認證方式

安裝完成後,需要在您的程式前面加上
import kyc
kyc.ApiConfig.api_key = "YOURAPIKEY"

分成以下三層API,包含

搜尋API(search api):

提供資料搜尋的功能,包含公司名稱、統一編號、住址搜尋,董監事名稱搜尋,集團搜尋...等功能。

報表API(report api):

提供整理後的公司資料、集團資料以及各類資料供應商的整合資料。

資料API(datatables api):

提供最基礎資料表格查詢與取得資料。

搜尋API使用方法(search api)

第一階段提供幾項搜尋,後續將陸續推出新功能

  • 公司名稱、統一編號、住址搜尋
  • 董監事名稱搜尋
  • 集團搜尋

[功能]搜尋公司名稱、統一編號、住址

針對公司名稱、統一編號、住址使用關鍵字搜尋,找出近似的結果。以【大西洋】為例
company_result = kyc.search_company("大西洋")
另可以使用參數rows限定最大回應筆數
company_result = kyc.search_company("大西洋",rows=100)

[功能]搜尋董監事名稱

針對董監事名稱使用關鍵字搜尋,找出近似的結果。以【施振榮】為例
director_result = kyc.search_director("施振榮")
另可以使用參數rows限定最大回應筆數
director_result = kyc.search_director("施振榮",rows=100)

[功能]搜尋集團資料

針對公司名稱、集團名稱使用關鍵字搜尋,找出近似的結果。以【臺灣水泥】為例
group_result = kyc.search_group("臺灣水泥")
另可以使用參數rows限定最大回應筆數
group_result = kyc.search_group("臺灣水泥",rows=100)

報表API使用方法(report api)

定義

第一階段提供以下報表,後續將陸續推出新功能

  • 公司資料報表
  • 集團資料報表

[功能]公司資料報表

公司ID代號找出公司報表資料,以【臺灣水泥股份有限公司】26914為例
company = kyc.get_company(26914)
公司統一編號找出公司報表資料,以【臺灣水泥股份有限公司】11913502為例
company = kyc.get_company(ban="11913502")

[功能]集團資料報表

針對集團資料提供整合式報告

以【嘉新集團】G1103為例
group = kyc.get_group("G1103")

資料API使用方式

以公司基本資料 TWN/MOEA_COMPANY為例,可直接使用 kyc.get()方法取得,範例如下

data = kyc.get('TWN/MOEA_COMPANY')
提示:

若沒有提供篩選條件,會取出所有資料,建議使用下段介紹的篩選方式,加入適當的篩選條件。

資料篩選

如果需要針對欄位篩選,例如僅須取得大西洋飲料股份有限公司(35012903),請直接增加欄位篩選條件 comp_ban='35012903'
data = kyc.get('TWN/MOEA_COMPANY',comp_ban='35012903')
                                    
或是同時取得兩個公司資料35012903及23740225,請利用序列條件 comp_ban=['35012903','23740225']
data = kyc.get('TWN/MOEA_COMPANY',comp_ban=['35012903','23740225'])
                                    
單次取得資料限制最多10,000筆,您可以增加 paginate=True,程式將自動分次取得資料
data = kyc.get('TWN/MOEA_COMPANY',comp_ban='35012903', paginate=True)
                                    
提示:

系統限制單次取得最大筆數為10000筆,可使用 paginate=True 參數分次取得資料,但總筆數最多為1,000,000筆。請斟酌使用篩選條件,降低筆數。

您可以針對多個欄位做篩選
data = kyc.get('TWN/MOEA_COMPANY',comp_status='核准設立', equity_status='僑外資' ,paginate=True)
                                    

欄位篩選

若僅需要取得單一欄位,請利用特殊參數 opts中的columns條件,例如僅須取得公司名稱欄位(comp_name) data = kyc.get('TWN/MOEA_COMPANY',opts={'columns':'comp_name'}) 或是多個欄位(comp_name,comp_ban) data = kyc.get('TWN/MOEA_COMPANY',opts={'columns':['comp_name','comp_ban']})

資料篩選運算

您可以針對資料欄位範圍篩選,例如設立日大於2018-01-01的資料 data = kyc.get('TWN/MOEA_COMPANY', set_date={'gt':'2018-01-01'}, paginate=True) 您可以針對資料欄位範圍篩選,例如設立日大於2018-01-01且小於2018-02-01的資料 data = kyc.get('TWN/MOEA_COMPANY', set_date={'gt':'2018-01-01','lt':'2018-02-01'}, paginate=True)
篩選運算
詳細說明
使用範例
=
指定欄位等於指定的文字或數值
comp_ban='35012903'
gt
指定欄位大於指定的數值
set_date={'gt':'2018-01-01'}
lt
指定欄位小於指定的數值
set_date={'lt':'2018-01-01'}
gte
指定欄位大於或等於指定的數值
set_date={'gte':'2018-01-01'}
lte
指定欄位小於或等於指定的數值
set_date={'lte':'2018-01-01'}
ne
指定欄位不等於指定的數值
set_date={'ne':'2018-01-01'}

查詢參數

參數
是否必要
詳細說明
使用範例
columns
指定需要取得的欄位,欄位名稱用逗號隔開
opts={'columns':['comp_ban','set_date','val']}
per_page
指定每次取得的資料數量(上限為10000),總筆數不得超過1,000,000筆
opts={'per_page':100}
sort
指定排序的欄位及排序方式,採用 [欄位名稱].[排序方式]表示,排序方式有正向排序(asc)及反向排序(desc),預設為正向排序。
opts={'sort':'set_date.desc'}
pivot
轉置表格功能,可讓資料變成欄位。目前僅支援財務相關表格
opts={'pivot':True}