特許情報の簡易取得パッケージ easy_patents

# 2022年01月28日　お知らせ
easy_patentsを修正のうえ再度公開しました。
既存でインストールされている方は、

```py
pip install easy-patents==1.0.2
```

でインストールのうえ、以下に記載のupdate_authinfo()を実行してください。

# 初めに
特許庁の[特許情報取得API](https://www.jpo.go.jp/system/laws/sesaku/data/api-provision.html)を簡単に使えるようにするためのpythonパッケージeasy_patentsを作成したので、本記事では、それを紹介する。

# easy_patents の特徴
(1)アクセストークンの取得を意識せずにAPIへのアクセスが可能
(2)簡易な指定が可能
(3)データをキャッシュするので、不必要な通信を避けることができる

## (1)アクセストークンの取得を意識せずにAPIへのアクセスが可能
アクセストークンの取得、更新は自動で行われる。最初にユーザ名とパスワードを設定することで、あとはアクセストークンの存在を意識せずにeasy_patentsを利用できる。

## (2)簡易な指定が可能
easy_patentsでは、

```py
progress_info = app_progress("特願2020-8423")
```


のように、API名(app_progress)と指定情報("特願2020-8423")だけを書けば、目的のjsonデータや実体審査ファイルなどが取得できる。

なお、出願番号などは、柔軟な指定が可能であり、全角と半角を混ぜたり、数字のみで指定したり、ハイフンの代わりにスラッシュを使ったりしてもよい。
例えば、全角で「特願２０２０／８４２３号」と指定してもよいし、2020008423と指定してもよい。
ただし、20208423のように、ハイフンやスラッシュ、ゼロのすべてを省略することはできない。これは、ハイフンやスラッシュを基準として、右側の数字のゼロ埋め処理を行っているためである。

## (3)データをキャッシュするので、不必要な通信を避けることができる
特許情報は、頻繁に更新されるものではないため、同じ情報取得のため、短期間のうちに何度もAPIへアクセスする必要はない。
この点に鑑みて、easy_patentsでは、すでに取得された情報については、一定期間中(defaultでは30日)は再取得をせずに、取得済みのファイル（キャッシュ）を返すようにした。ファイルの更新期間は、引数reget_dateで指定可能である。

```py
progress_info = app_progress("特願2020-8423", reget_date=15)
```

上記の場合、既存のデータが15日以内のデータであれば再取得はせずに既存のデータが返される。

なお、reget_date=0とすることで、即時取得が可能である。

# 使い方

## 前提条件
python3.6以上
特許庁にAPI利用申請をし、usernameとpasswordを知らされていること。

## インストール

```py
pip install easy-patents
```

## 認証情報設定

コマンドプロンプトやWindows Power Shellなどを立ち上げて、pythonと打ち込むことで、pythonのシェルが起動する。
そして、以下の通り実行すると、トークン取得パス,username, passwordの入力プロンプトが出るので、特許庁から送付されたトークン取得パス,username, passwordを入力する。

```py
$ python
>>> from easy_patents.update_authinfo import update_authinfo
>>> update_authinfo()
token_path:
username:
password:
```

※トークン取得パス, username, passwordについては、特許庁から送付されたそのままの値を入力すること。(urlencodeなどはプログラム内部で行われる)

なお、入力中のパスワードを表示させたい場合には、以下のようにすればよい。

```py
>>> update_authinfo(display_password=True)
```

## サンプル実行

```py
$ python
>>> from easy_patents.get_info import app_progress
>>> progress_info = app_progress("特願2020-8423")
>>> progress_info['result']['data']['inventionTitle']
'管理システム及び管理方法'
```

なお、実行時に末尾に以下のように表示された場合には、usernameかpasswordが間違っているため、update_autuinfo()を再実行する必要がある。

```
KeyError: 'access_token'
```

また、実行時に以下のように表示された場合には、[Visual C++ 再頒布可能パッケージ](Visual C++ 再頒布可能パッケージ) のインストールと再起動を行う必要がある。

```
ImportError: DLL load failed: 指定されたモジュールが見つかりません。
```

## 使用可能な関数

使用可能な関数名を、引数と共に表示する。


```py
app_progress(case_number, reget_date=30)
app_progress_simple(case_number, reget_date=30)
divisional_app_info(case_number, reget_date=30)
priority_right_app_info(case_number, reget_date=30)
applicant_attorney_cd(code, reget_date=30)
applicant_attorney(name, reget_date=30)
application_reference(case_number, reget_date=30)
publication_reference(case_number, reget_date=30)
registration_reference(case_number, reget_date=30)
app_doc_cont_opinion_amendment(case_number, reget_date=30)
app_doc_cont_refusal_reason_decision(case_number, reget_date=30)
app_doc_cont_refusal_reason(case_number, reget_date=30)
cite_doc_info(case_number, reget_date=30)
registration_info(case_number, reget_date=30)
```

いずれも、以下のようにしてインポートして使用することができる。

```py
from easy_patents.get_info import registration_info
info = registration_info("特願2020-8423", reget_date=10) 
```

なお、application_reference, publication_reference, registration_reference以外の関数については、同名のAPIに対してアクセスする関数である。APIの詳細については、[APIの仕様書](https://ip-data.jpo.go.jp/api_guide/api_reference.html#/)を参照のこと。
application_reference, publication_reference, registration_reference以外の関数におけるcase_numberは出願番号、codeは申請人番号、nameは申請人名である。
regit_dateは再取得までの日数（＝キャッシュの有効期間）である。

application_referenceは、case_number_referenceで種別をapplicationとしたもの。case_numberは出願番号。
publication_referenceは、case_number_referenceで種別をpublicationとしたもの。case_numberは公開・公表番号。
registration_referenceは、case_number_referenceで種別をregistrationとしたもの。case_numberは登録番号。

また、出願番号等を半角や特定の漢字無視をして変換する関数として、以下を使用できる。

```py
easy_patents.get_info.convert_key(key)
```

このほかの関数については、将来的に廃止や変更を行う可能性があるため、使わない方が良い。

## 戻り値
いずれも関数名に対応するAPIの情報を取得する。

jsonデータの場合には、jsonデータが返答される。
なお、このjsonデータには、easy_patents内部で使用するep_dataが付加されている。
zipデータの場合には、zip解凍先のディレクトリのパスが返される。

## 例外
APIの[ステータスコード](https://ip-data.jpo.go.jp/pages/api_status.html)に応じていくつかの例外が発生する。

```py
NoDocumentError
　statusCodeが107, 108, 111の時に発生するエラー

ParameterError
　statusCodeが204, 208, 212, 301, 400の時に発生するエラー

TooManyAccessError
　statusCodeが203の時に発生するエラー

TemporaryError
　statusCodeが210, 302, 303の時に発生するエラー

UnknownError
　statusCodeが999かその他定義されていないコードの時に発生するエラー
```

なお、ステータスコード210, 302, 303については、例外をすぐには発生させずに、最大3回まで1秒スリープでリトライする。

いずれの例外も、以下のようにしてインポートすることができる。

```py
from easy_patents.errors import UnknownError
```

## キャッシュクリア
キャッシュはコマンドプロンプトなどで以下のコマンドで削除できる。

```
<easy_patentsがインストールされているディレクトリ>/delete_caches.py <削除対象のキャッシュの経過日数>
```

もしくは、pythonシェルやスクリプトで以下のようにして削除してもよい。

```py
>>> from easy_patents.delete_caches import delete_caches
>>> delete_caches(delete_before=<削除対象のキャッシュの経過日数>)
```

なお、全てのキャッシュを削除したい場合には、easy_patentsがインストールされているディレクトリ配下のdataディレクトリを削除すればよい。

# 免責事項
easy_patentsは、とある弁理士が開発したものである。利用者はeasy_patentsを自己の責任で使うこと。easy_patentsの使用によって発生したいかなる損害についてもeasy_patentsの開発者は責任を負わない。

#問合せ先
tiwtter: [@EasyPatents39](https://twitter.com/EasyPatents39)
email: easypatents39@gmail.com