見出し画像

大学ポートレートのWebAPI機能を利用してみた

Pogo / gmoriki

2022年8月25日より、大学ポートレート Web-API機能の提供を開始しました。
Web-API機能は、大学ポートレートセンターが各参加機関より収集し公表しているデータを機械判読が容易なデータ形式（JSON）で提供するもので、ユーザ登録いただければどなたでもご利用になれます。

大学ポートレート Web-API機能ウェブサイト
https://api-portal.portraits.niad.ac.jp/index.html

https://portraits.niad.ac.jp/info/-web-api.html

大学ポートレートが登録ユーザ向けAPIを提供している。全く知らなかった。個別大学ごとの情報を取得したい時に便利かもしれない。
個人的にも本当に助かる。現状、各所のとんでもないExcelデータをクレンジングする他ないと考えていたので大変ありがたい。

早速PythonでAPIを叩いてみよう。

📢
本記事は独立行政法人大学改革支援・学位授与機構が運用する大学ポートレートのWeb-API機能を使用していますが、本記事の内容は私(Pogo / gmoriki)の責に帰するものです。

■ アクセスキーの取得

こちらよりユーザ登録を行うと数日後にアクセスキーが送付される。

■ 取得可能なデータ種別

WebAPIの仕様はこちら：
https://api-portal.portraits.niad.ac.jp/Web-API-specVer1.0.pdf

取得可能なデータは非常に多い。

  • 学生教員等状況票API情報取得

  • 学部学生内訳票API情報取得

  • 大学院学生内訳票API情報取得

  • 本科学生内訳票API情報取得

  • 外国人学生調査票API情報取得

  • 卒業後の状況調査票(2-1)API情報取得

  • 卒業後の状況調査票(2-2)API情報取得

  • 学校施設調査票API情報取得

例えば学生教員等状況票API情報取得の返却値を以下に示す。

  • 大学

  • 学生数

  • 教員数(本務者)

  • 教員数(本務者)内訳

  • 教員数(兼務者)

  • 教員数(兼務者)のうち外国人

  • 職員数

  • 学校基本情報

更にそれぞれの下位層には種別ごと・性別ごとの集計数が保持されている。
すごい。

URIに用いられるパラメータは以下の通りである。

https://api-portal.portraits.niad.ac.jp/Web-API-specVer1.0.pdf

API種別によって組織IDの形式が異なるので注意。

文中の別紙「大学ID一覧」、「外国人学生用組織ID一覧」：

https://api-portal.portraits.niad.ac.jp/soshikiIDlist_20221228.pdf

■ 実装例

参考：開発サンプル

Pythonの開発サンプルはこちら。

サンプルでは学部学生内訳票APIを利用して、学部生数を出力している。

#!/usr/local/bin/python3.4

import os, sys, io, cgi, requests
import urllib3
from urllib3.exceptions import InsecureRequestWarning
urllib3.disable_warnings(InsecureRequestWarning)
# *************　パラメータ設定　*************　
search_url = "https://edit.portraits.niad.ac.jp/api/v1/SchoolBasicSurvey/getCollegeUndergraduateStudentsDetail"
payload = {"accesskey":"<アクセスキー>",
  "year":"<年度>",
  "orgid":"<組織ID>"
}

# *************　API呼び出し　*************　
res = requests.get(search_url, params=payload, verify=False)
data = res.json()

sumgakuseisu = 0
if data['GET_STATUS_LIST']['RESULT']['STATUS'] == '0':
    for gakkagakuseisu in data['GET_STATUS_LIST']['DATALIST_INF']['DATA_INF'][0]['CONTENT']['GAKKA_GAKUSEI_SU']:
        if gakkagakuseisu['GAKKA']['GAKKA_MEI'] == '計':
            sumgakuseisu = int(gakkagakuseisu['GAKKA']['GAKUSEI_SU_KEI_M']) + int(gakkagakuseisu['GAKKA']['GAKUSEI_SU_KEI_F'])
                
# *************　取得データの表示　*************　
print('XX大学XX部学生数：' + str(sumgakuseisu) + '人')

ここから実装開始。
今回は関数定義のうえ、学部学生内訳票API以外のAPIを利用してみた。

○ 関数・変数の定義

指定したAPIタイプ、年度、および組織IDを使用して、コンテンツデータを取得します。 この関数は指定したURLからJSON形式のデータを取得し、その中から特定のコンテンツデータを抽出します。

import requests

base_url = "https://edit.portraits.niad.ac.jp/api/v1/SchoolBasicSurvey/"
accesskey = "XXXX"  # ご自身のキーを設定ください


# *************　関数定義　*************
def retrieve_content_data(api_type, year, orgid):
    """
    指定したAPIタイプ、年度、および組織IDを使用して、コンテンツデータを取得します。

    この関数は指定したURLからJSON形式のデータを取得し、その中から特定のコンテンツデータを抽出します。

    Parameters:
    api_type (str): APIの種類を示す文字列です。APIのエンドポイントに対応しています。
    year (int or str): 情報を取得する年度を示します。
    orgid (str): 情報を取得する組織のIDを示します。必要なIDはAPIの種類によって異なります。

    Returns:
    dict: 取得したコンテンツデータ。JSON形式のデータから抽出されます。

    Example:
    >>> content = retrieve_content_data("getSchoolFacilities", 2021, "0292")
    >>> print(content)
    { ... }

    Note:
    実行する前に`base_url`と`accesskey`が適切に設定されていることを確認してください。
    また、HTTPSリクエストはSSL/TLS証明書の検証を行います。
    """
    search_url = base_url + api_type
    payload = {"accesskey": accesskey, "year": year, "orgid": orgid}

    # *************　API呼び出し　*************
    res = requests.get(search_url, params=payload, verify=True)
    jsondata = res.json()

    status_flg_dict = jsondata["GET_STATUS_LIST"]["RESULT"]

    if status_flg_dict["STATUS"] != "0":
        print(status_flg_dict["ERROR_MSG"])
        return status_flg_dict["ERROR_MSG"]

    content_data = jsondata["GET_STATUS_LIST"]["DATALIST_INF"]["DATA_INF"][0]["CONTENT"]

    return content_data

取得したレスポンスのjsonデータを覗いてみると、以下に成功/失敗フラグと失敗時のエラーメッセージが格納されている。
本来ならこの辺で例外処理を行う。

jsondata["GET_STATUS_LIST"]["RESULT"]

また全APIに共通するデータ保存先は以下の通り。多分。

jsondata["GET_STATUS_LIST"]["DATALIST_INF"]["DATA_INF"][0]["CONTENT"]

こいつを取得できれば煮るなり焼くなりできる。

○ 学生教員等状況票API

# *************　データの取得・表示　*************

# %%
# 学生教員等状況票API情報取得
# XX大学の職員数を取得

base_data = retrieve_content_data("getStudentFacultyStatus", 2021, "0292")

shokuin_data = base_data["SHOKUIN_SU"][0]
print("XX大学の職員数:" + shokuin_data["SHOKUIN_SU_KEI"])
# 出力例
# 職員数:hogehog


○ 大学院学生内訳票API

# %%
# 大学院学生内訳票API情報取得
# XX大学の入学志願者数(男)を取得

base_data = retrieve_content_data("getGraduateStudentsDetail", 2021, "0256-64-22-GS01-09-1")

nyugaku_data = base_data["NYUGAKU_JOKYO"]["SENKO"][0]
print("XX大学の入学志願者数(男):" + nyugaku_data["NYUGAKU_SHIGANSHA_SU_KEI_M"])
# 出力例
# 入学志願者数(男):hogehoge


○ 本科学生内訳票API ※

※ うまく動きませんでした…。
限られた大学IDでしか動かないのかもしれない。
(大学ポートレートのデータに疎くてすみません)

ダメそうなら問い合わせてみます。

# %%
# 本科学生内訳票API情報取得

# うまくいくはずなのに「該当データなし」になる...?
base_data = retrieve_content_data("getJuniorCollegeUndergraduateStudentsDetail", 2021, "0172")


○ 外国人学生調査票API

# %%
# 外国人学生調査票API情報取得
# XX大学におけるタイからの留学生数(女)を取得

base_data = retrieve_content_data("getForeignStudent", 2021, "0292-1Z11")
ryugakusei_data = base_data["RYUGAKUSEI"][0]["GAKUMON_KOKUBETSU"]
print("タイからの留学生数(女):" + ryugakusei_data["CHIIKI"][0]["KUNI_GAKUSEI_SU_KEI_F"])
# 出力例
# タイからの留学生数(女):hogehoge


○ 卒業後の状況調査票(2-1)API

# %%
# 卒業後の状況調査票(2-1)API情報取得
# XX大学院研究科に進学した学部生数(男)を取得

base_data = retrieve_content_data("getStatusAfterGraduationGraduates", 2021, "0292-27-27-1G01-00-1")
sotugyo_data = base_data["GAKKA_SENKO"][0]["JOKYO_SOTSUGYOSHA_SU"][0]
print("XX大学院研究科に進学した学部生数(男):" + sotugyo_data["SOTSUGYOSHA_SU"][0]["SOTSUGYOSHA_SU"])
# 出力例
# XX大学院研究科に進学した学部生数(男):hogehoge


○ 卒業後の状況調査票(2-2)API

# %%
# 卒業後の状況調査票(2-2)API情報取得
# 産業分類Eに就職した学生数(男)

base_data = retrieve_content_data("getStatusAfterGraduationJobs", 2021, "0292-27-27-1G01-00-1")
sotugyo_data = base_data["GAKKA_SENKO"][0]["SANGYO_SHUSHOKUSHA_SU"]["SHUSHOKUSHA_SU"]

sangyo_name = "E 製造業／7 電子部品・デバイス・電子回路製造業"

# 特定の産業分類に就職した学生数を出力
for sangyo_datum in sotugyo_data:
    if (sangyo_datum["SHUSHOKUSHA_SANGYO_BUNRUI"] == sangyo_name) & (sangyo_datum["SHUSHOKUSHA_SEX"] == "男"):
        print("産業分類Eに就職した学生数(男):" + sangyo_datum["SHUSHOKUSHA_SU"])
# 出力例
# 産業分類Eに就職した学生数(男):hogehoge


○ 学校施設調査票API

# %%
# 学校施設調査票API情報取得
# XX大学の寄宿舎施設の面積を取得

base_data = retrieve_content_data("getSchoolFacilities", 2021, "0292")

area_yoto = "寄宿舎施設"

for area_datum in base_data["GAKKO_TOCHI_YOTO_AREA"][0]["AREA"]:
    if area_datum["AREA_YOTO"] == area_yoto:
        print("寄宿舎施設の面積:" + area_datum["AREA"] + area_datum["AREA_TANI"])
# 出力例
# 寄宿舎施設の面積:hogehoge㎡

🎨
各APIごとに異なるデータ構造を持つ。
例えばリストのryugakusei_data["CHIIKI"]。ryugakusei_data["CHIIKI"][0]はタイからの、ryugakusei_data["CHIIKI"][1]はシンガポールからの留学生の情報を持つ。
API利用の際は仕様を参照しつつ探索的or再帰的にキーを探すしか無い、と思う。

◇ GitHub

Githubにも公開しました。ぼちぼち充実させる予定です。
アクセスキーは各自ご準備ください。


いいなと思ったら応援しよう！