６．ライブラリの利用

住所データベースが作成された後はライブラリが利用できるようになります。ライブラリの使用方法は次のとおりです。

６．１　住所データベースのメモリへの格納

ライブラリを使用する最初に、住所データベースをメモリにロードします。
(例）

path = "/data/address_data";      // 住所データベースの格納ディレクトリ 
loadLevel = 4;               　   // 地番街区符号のデータまでをロード  
retCode =  gcjDbLoad( path, loadLevel );

６．２　文字コードの設定

次に、関数で受け渡しする住所文字列の文字コードを設定します。シフトJISの場合は設定しなくても構いません。
(例）

retCode = gcjSetArgEncoding( "EUC-JP" );

６．３　住所を緯度経度に変換

住所を緯度経度に変換する場合は、次の２つのステップで行います。
１）住所を住所コードに変換する。
２）住所コードを緯度経度に変換する。
(例）

char *address;
ADR_CODE adrCode;
double latitude,longitude;
address = "東京都千代田区丸の内一丁目２番３号"
 
//　住所を住所コードに変換
retCode = gcjAdrStr2Code( address, &adrCode );
 
// 住所コードを緯度経度に変換
retCode = gcjAdrCode2Point( &adrCode, &latitude, &longitude);

６．４　住所を正規化

住所を統一した書式に変換（正規化）する場合は、次の２つのステップで行います。
１）住所を住所コードに変換する。
２）住所コードを住所文字列に変換する。
(例）

char *address,kanji[256];
ADR_CODE adrCode;
double latitude,longitude;
address = "東京都千代田区丸ノ内1-2-3"　　　
 
//　住所を住所コードに変換
retCode = gcjAdrStr2Code( address, &adrCode );      
 
// 住所コードを住所文字列に変換
retCode = gcjAdrCode2Str( &adrCode, kanji, 256, NULL, 0 );      
 
// kanji[]には"東京都千代田区丸の内一丁目２番３号"が返ります。

出力形式を変更したい場合はgcjSetAdrStringFormat()で形式を設定します。
（例）丁目の数字を算用数字で出力する場合

retCode = gcjSetAdrStringFormat( 21, 0 );
retCode = gcjAdrCode2Str( &adrCode, kanji, 256, NULL, 0 );
// kanji[]には"東京都千代田区丸の内１丁目２番３号"が返ります

６．５　ライブラリの利用終了処理

ライブラリの使用が終了した場合は、住所データベースなどライブラリ用に確保したメモリを解放します。この処理は必ず行って下さい。
（例）

retCode = jcjDbEnd();

６．６　住所コード

ライブラリの関数で、住所を緯度経度へ変換したり、正規化するだけであれば、ライブラリで使われている住所コードに関して知る必要はありません。しかし、住所データベースの内容に直接アクセスして、より柔軟な対応を行うといった場合は、住所コードについての知識が必要です。以下に住所コードについて解説いたします。
住所コードは以下の構造体です。

typedef struct {
    int codeLevel; /* コードが有効なレベル　*/
    int cityCode;  /* 市区町村コード(JIS) 5桁 　　：レベル１～４　*/
    int choCode;   /* 町大字コード（独自）    　　：レベル５　*/
    int azaCode;   /* 丁目字コード（独自）     　 ：レベル６　*/
    int gaikuCode; /* 地番街区符号コード（独自）　：レベル７　*/
    int jukyoCode; /* 枝番住居番号コード（独自）  ：レベル８　*/
} ADR_CODE ;

ここで、｢コードが有効なレベル｣とは、この構造体に格納されているコードのうち、上位レベルからどのコードまで有効な値が入っているかを示す値です。例えば、codeLevelの値が６の場合は丁目字コードまで有効な値として利用できる事を示します。
また、コード番号が下位のレベルまで有効な値が入っていても、より上位のレベルのコード番号を関数に渡したい場合はcodeLevelを渡したいレベルの値にして使用するという使い方もできます。
市区町村コードはレベル１～４となっていますが、これは

都道府県レベル　：　レベル１
支庁レベル　　　：　レベル２
郡レベル　　　　：　レベル３
市区町村レベル　：　レベル４

の４つのレベルをまとめています。これは５桁の市区町村コードの番号を解析する事で上位のコード番号を求める事ができるからです。

６．７　住所データベースへの直接アクセス

住所データベースのレコードを直接読み出す場合は次のようにします。

１．読み出したいデータの住所コードが分かっている場合
　　gcjGetAdrRecord()で直接読み出す事ができます。
２．ある市の町大字名を全て読み出したいといった場合
　１）読み出したいレベルの住所データのレコード数を取得します。
　２）そのレコード数のintの配列を確保します。
　３）その配列にレコードのコード番号のリストを読み込みます。
　４）配列のコード番号を指定してレコードを取得します。

（例）東京都新宿区の町大字レコードの最初のレコードを取得する場合

ADR_CODE adrCode;
int *codeNumｓ;
CHO_RECORD choRecord;
adrCode.codeLevel = 5;　　     // 町大字区域を表すコードは5
adrCode.cityCode = 13104;    // 新宿区の市区町村コードは13104　　　
 
// numReordsに町の数が返されます。
numRecords =  gcjGetNumAdrRecords( &adrCode );　　　　
 
// 町の数分のintの配列を確保します。
codeNumｓ = (int*) malloc( numRecords * sizeof(int) );      
 
// codeNumsの配列にコード番号が格納されます。
numCodes = gcjGetAdrRecordList( &adrCode, codeNumｓ, numRecords );      
 
// 最初のレコードがrecordに格納されます。
adrCode.choCode = codeNums[0];
result = gcjGetAdrRecord( &adrCode, (void*) &choRecord, sizeof(record) );