estatapiパッケージで簡単にe-Statのデータ取得

諸事情によりe-Statのデータを取得する必要がでたので、estatapiパッケージの紹介がてらメモを。

## 登録とappId発行
e-Statを利用するためにはappIdが必要です。まだ取得していない方は、以下の手順で取得してください。

1. [e-StatのAPI機能のサイト](http://www.e-stat.go.jp/api/)へ
2. 利用登録へ
3. メアド登録してメールを受信し、本文内にあるリンク先へ
4. 本登録画面が出るので必要事項を入力
5. 本登録が完了したら、1のAPI機能トップサイトからログイン
6. 「アプリケーションIDの取得」で、appIdを発行する

## estatapiパッケージ
このパッケージは@yutannihilation さんが開発したパッケージです。本人のブログ記事に紹介が記載されております:

- [e-Stat APIをRから使うパッケージを作りました - Technically, technophobic.](http://notchained.hatenablog.com/entry/2015/11/01/084909)

### 利用する関数
主に以下の3つの関数で構成されています:

- estat_getStatsList(): 検索ワードに基づき、条件に一致した統計表のリストを取得します。
- estat_getMetaInfo(): 指定した統計表が保有するメタデータを取得します。
- estat_getStatsData(): 指定した条件に基づき、統計表からデータを取得します。

手順としては…

1. estat_getStatList関数で、使いたい統計表をみつける
2. estat_getMetaInfo関数で、使う統計表のメタデータを確認(して目星をつける)
3. estat_getStateData関数で、ほしいデータを取得する

となります。CRANに登録されているので`install.packages()`でインストールできます。

```r
install.packages("estatapi")
```

## 具体例
実際にデータを持ってくるサンプルコードを用いて紹介します。

今回使用したいデータは[平成23年度社会生活基本調査](http://www.stat.go.jp/data/shakai/2011/)内の、生活時間における睡眠のデータがほしいとします。API機能で利用するためには**政府統計コード**が必要になってくるとのこと。これは[こちらの一覧](http://www.e-stat.go.jp/api/api-data/)から探してきます。でも今回は使いたい調査名などはわかっていたし、**検索ワードがわかれば問題ない**のでスルーしました。

### 必要な統計表を検索する
ではターゲットのデータリストを取得してみます。なお`appId`はすでに`myappID`に格納してあることとします:

```{r cache=TRUE}
library(estatapi)
StatsList <- estat_getStatsList(appId = myappId, searchWord = "社会生活基本調査")
str(StatsList)
```

```
## Classes 'tbl_df', 'tbl' and 'data.frame':	5265 obs. of  13 variables:
##  $ @id                 : chr  "0003005834" "0003005836" "0003005838" "0003070357" ...
##  $ STAT_NAME           : chr  "社会生活基本調査" "社会生活基本調査" "社会生活基本調査" "社会生活基本調査" ...
##  $ GOV_ORG             : chr  "総務省" "総務省" "総務省" "総務省" ...
##  $ STATISTICS_NAME     : chr  "平成18年社会生活基本調査 調査票Ｂに基づく結果 生活時間に関する結果 生活時間編" "平成18年社会生活基本調査 調査票Ｂに基づく結果 生活時間に関する結果 生活時間編" "平成18年社会生活基本調査 調査票Ｂに基づく結果 生活時間に関する結果 生活時間編" "平成23年社会生活基本調査 調査票Ｂに基づく結果 生活時間に関する結果 生活時間編" ...
##  $ TITLE               : chr  "男女，行動の種類（小分類，主行動），行動の種類（小分類，同時行動）別総平均時間（週全体）" "男女，行動の種類（小分類，主行動），行動の種類（小分類，同時行動）別行動者平均時間（週全体）" "男女，行動の種類（小分類，主行動），行動の種類（小分類，同時行動）別行動者率（週全体）" "男女，主行動の種類(小分類)，同時行動の種類(小分類)別総平均時間－週全体" ...
##  $ CYCLE               : chr  "-" "-" "-" "-" ...
##  $ SURVEY_DATE         : chr  "200610" "200610" "200610" "201110" ...
##  $ OPEN_DATE           : chr  "2007-12-21" "2007-12-21" "2007-12-21" "2012-12-21" ...
##  $ SMALL_AREA          : chr  "0" "0" "0" "0" ...
##  $ MAIN_CATEGORY       : chr  "教育・文化・スポーツ・生活" "教育・文化・スポーツ・生活" "教育・文化・スポーツ・生活" "教育・文化・スポーツ・生活" ...
##  $ SUB_CATEGORY        : chr  "文化・スポーツ・生活" "文化・スポーツ・生活" "文化・スポーツ・生活" "文化・スポーツ・生活" ...
##  $ OVERALL_TOTAL_NUMBER: chr  "39675" "39675" "39675" "43200" ...
##  $ UPDATED_DATE        : chr  "2009-03-09" "2009-03-09" "2009-03-09" "2013-01-07" ...
```

**(2016/05/27追記)**出力結果が以前と変化していたので差し替えました。

`estat_getStatsList`を実行するとちょっと時間かかりますが、うまくいけばこのようにデータを取得できます。

#### 引数について
`appId=`はe-Stat APIを利用するためのapppIdです。必須です。  
`searchWord`は検索キーワードです。今回は調査名を入れましたが、ヒットさえすれば"チョコレート"とかでもOKです。ただ相当な検索結果になると面倒なので、事前にe-Statである程度検索しておくと楽だと思います。

**(2016/01/29追記)**あと、上記以外のAPIパラメータにも対応しているようで、いくつか動作確認しました。例えば必要なデータの政府統計コードがわかっている場合、それを利用して以下のように絞り込むことができます:

```r
> StatsList <- estat_getStatsList(appId = myappId, searchWord = "", statsCode = "00450012")
> str(StatsList)
Classes ‘tbl_df’, ‘tbl’ and 'data.frame':	2 obs. of  11 variables:
 $ @id                 : chr  "0003109570" "0003109558"
 $ @code               : chr  "03" "03"
 $ $                   : chr  "人口動態" "人口動態"
 $ STATISTICS_NAME     : chr  "生命表 完全生命表" "生命表 簡易生命表"
 $ TITLE               : chr  "完全生命表" "簡易生命表"
 $ CYCLE               : chr  "-" "年次"
 $ SURVEY_DATE         : chr  "0" "0"
 $ OPEN_DATE           : chr  "2015-09-30" "2015-09-30"
 $ SMALL_AREA          : chr  "0" "0"
 $ OVERALL_TOTAL_NUMBER: chr  "3880" "10944"
 $ UPDATED_DATE        : chr  "2015-12-02" "2015-12-02"
```

ただしこの場合、`searchWord=`引数に何らかの値(""を含む)を指定していないとエラーが出ます。また何らかの縛りをしておかないと膨大な量が返ってくるので注意してください。

このパラメータに関しては[API仕様](http://www.e-stat.go.jp/api/api-spec/)をご覧ください[^1]。

[^1]: APIの仕様通りに指定すれば仕様通り返ってくるとは思います…。

#### 出力について
data.frame(正確にはtbl_df)で出力されます。大切なものだけ説明します:

- `@id`: 統計表のidです。次のステップ以降ではこれが必要になります。
- `STATISTICS_NAME`: 統計名です。
- `SURVEY_DATA`: データの調査時期です。

これら3つやその他の部分をのぞきつつ、必要な統計表を探します。見つけたら、その統計表idを確保してください。今回は"0003066844"の統計表とします。

### 統計表のメタ情報を取得
統計表idを取得したら、そのメタ情報を取得します:

```r
meta_info <- estat_getMetaInfo(appId = myappId, statsDataId = "0003066844")
names(meta_info)
```

```
## [1] "cat01" "cat02" "cat03" "cat04" "area"  "time"
```

#### 引数について
`statsDataId=`は統計表idを指定します。このestat_getMetaInfo関数の2つの引数は必須です。

#### 出力について
data.frameをまとめたリストが返ってきます。返ってくる内容については各統計表によって大分違うので、必ずそれぞれを確認してください。今回の例では、必要なのは**各時間帯における睡眠率(`meta_info$cat01$"@id"="002"`)**で、地域のデータではなく**全国(`meta_info$area$"@id"="00000"`)**のデータがほしいとします。  
ようするに、**使いたい項目の`@id`の値**と**そのデータフレーム名**をおさえておけばOKです。

### 指定したメタ情報を基に、統計表からデータを取得
これで準備はできたので、統計表からデータを取得します:

```r
df <- estat_getStatsData(
  appId = myappId,
  statsDataId = "0003066844",
  cdCat01 = "002",
  cdArea = "00000")
```

#### 引数について
`cdCat01=`や`cdArea=`などは、メタ情報を利用して必要なデータを絞り込んでいます。メタ情報で得たデータフレーム名の頭文字を大文字にし、そのまえに"cd"をつけてください。右辺は`@id`の値です。  
つまり、`cdCat01="002"`は、「"cat01"の中にあった`@id="002"`の項目」という意味です。なお「`@id=002`と`@id=003`の両方ほしい」という場合は、`cdCat01=c("002","003")`としてください。

他に引数として、`limit=`があります。これは取得するデータ数の上限を指定します。`limit=200`と指定すると、200件を取得してきます。ちなみに仕様として一度に取得できるのが10万件までです。これ以上を超えると、その続きから取得しなければなりません。  
上限に達した場合、もしくは小分けにして続きから取得したい場合は、`startPosition=`の引数で指定してください。`startPosition=201`とすると、201件目から取得してきます。

#### 出力について
data.frameで返ってきます。各変数については実際にデータを眺めてみれば早いでしょう。メタ情報とのヒモ付も自動でされています。

ちなみに、この場合以下のようになっていました:

```r
str(df)
```

```
## Classes 'tbl_df', 'tbl' and 'data.frame':	882 obs. of  15 variables:
##  $ @cat01    : chr  "002" "002" "002" "002" ...
##  $ @cat02    : chr  "001" "001" "001" "001" ...
##  $ @cat03    : chr  "001" "001" "001" "099" ...
##  $ @cat04    : chr  "00100" "00200" "00300" "00100" ...
##  $ @area     : chr  "00000" "00000" "00000" "00000" ...
##  $ @time     : chr  "2011000000" "2011000000" "2011000000" "2011000000" ...
##  $ $         : chr  "-" "-" "-" "-" ...
##  $ @unit     : chr  NA NA NA "千人" ...
##  $ value     : num  NA NA NA NA NA ...
##  $ cat01_info: chr  "睡眠" "睡眠" "睡眠" "睡眠" ...
##  $ cat02_info: chr  "総数" "総数" "総数" "総数" ...
##  $ cat03_info: chr  "標本数" "標本数" "標本数" "10歳以上推定人口" ...
##  $ cat04_info: chr  "平日" "土曜日" "日曜日" "平日" ...
##  $ area_info : chr  "全国" "全国" "全国" "全国" ...
##  $ time_info : chr  "2011年" "2011年" "2011年" "2011年" ...
```


```r
knitr::kable(head(df,9))
```



|`@cat01` |`@cat02` |`@cat03` |`@cat04` |`@area` |`@time`      |`$`     |`@unit` | `value`|`cat01_info` |`cat02_info` |`cat03_info`          |`cat04_info` |`area_info` |`time_info` |
|:------|:------|:------|:------|:-----|:----------|:-----|:-----|-----:|:----------|:----------|:-------------------|:----------|:---------|:---------|
|002    |001    |001    |00100  |00000 |2011000000 |-     |NA    |    NA|睡眠       |総数       |標本数              |平日       |全国      |2011年    |
|002    |001    |001    |00200  |00000 |2011000000 |-     |NA    |    NA|睡眠       |総数       |標本数              |土曜日     |全国      |2011年    |
|002    |001    |001    |00300  |00000 |2011000000 |-     |NA    |    NA|睡眠       |総数       |標本数              |日曜日     |全国      |2011年    |
|002    |001    |099    |00100  |00000 |2011000000 |-     |千人  |    NA|睡眠       |総数       |10歳以上推定人口    |平日       |全国      |2011年    |
|002    |001    |099    |00200  |00000 |2011000000 |-     |千人  |    NA|睡眠       |総数       |10歳以上推定人口    |土曜日     |全国      |2011年    |
|002    |001    |099    |00300  |00000 |2011000000 |-     |千人  |    NA|睡眠       |総数       |10歳以上推定人口    |日曜日     |全国      |2011年    |
|002    |001    |003    |00100  |00000 |2011000000 |82.93 |％    | 82.93|睡眠       |総数       |行動者率(0:00-0:15) |平日       |全国      |2011年    |
|002    |001    |003    |00200  |00000 |2011000000 |82.12 |％    | 82.12|睡眠       |総数       |行動者率(0:00-0:15) |土曜日     |全国      |2011年    |
|002    |001    |003    |00300  |00000 |2011000000 |80.86 |％    | 80.86|睡眠       |総数       |行動者率(0:00-0:15) |日曜日     |全国      |2011年    |

無事に取得できましたが、まともに使うにはここからさらに前処理が必要になります…でも取得が相当簡単になることは伝わるかと思います。ぜひ色々やってみてください。

なお、この内容は、政府統計総合窓口(e-Stat)のAPI機能を使用していますが、サービスの内容は国によって保証されたものではありません。

Enjoy!