API利用ガイド

FrontPage

API利用ガイド

事前情報の取得†

IMD食品栄養データAPIの使用に当たっては、以下の各設定情報が必要となる。
（※使用に際し弊社より発行し、別途通知します）

APIサーバー名・アクセスコード†

APIのエントリポイントは、サーバー名とアクセスコードを使用して構成する。

アクセス認証†

APIを利用する上で正しいアクセス元であることを確認するため、アクセス元IPアドレスの制限、Authorizationヘッダーの送出、のいずれかまたは両方が必要である。

アクセス元IPアドレスの制限†

APIはIPアドレスによってアクセスを制限する。使用に際しては、アクセス元となるIPアドレスを設定する必要がある。（※弊社にて設定しますのでアドレスをお知らせ下さい）

Authorizationヘッダーの送出†

APIはAuthorizationヘッダーによってアクセスを認証する。クライアントは全てのアクセスに際して、HTTPリクエストヘッダーに以下の通りアクセストークンを送出する。（※弊社にてトークンを振りだしますのでご連絡ください）
アクセストークンは、他者に漏れないよう、正しく管理されなければならない。

Authorization: Bearer (アクセストークン)

Authorizationヘッダーは、typeをBearerとし、credentialsにアクセストークン文字列を指定する。アクセストークンについてはOAuth2.0の仕様に準じ、長さ不定の半角英数記号による文字列とする。
アクセストークンによる認証が成功した場合、HTTPレスポンスコード200を返却する。レスポンスヘッダーに X-MobadaiApi-Authenticated が含まれ、値は true となる。
アクセストークンによる認証に失敗した場合、HTTPレスポンスコード401を返却する。レスポンスヘッダーに X-MobadaiApi-Authenticated は含まれない。

例:
$ curl -H 'Authorization: Bearer TVBJb3lvQ2VlbzlVVzZXNUFWZkladXhSVU5hcDQrREp1QWt6Z0hKM21qNU5OaEFsTnpvOXpWUDJ5TytKM0NXUjc2VEdTRG94RVRheVVScmZ6UGxHZzRmaDlqZm9HWm56cEZHTG4yUEx5eTRRWFFRLzlRelRSTmhtL3dLaW9OZU5aejBLS053cXV6bGdNQ0M4MVl4MXZmN21kRlFhQlhRd0pYMFBmZW95UXZkOTBNZ25HR2VPNGZ0Wk1CZmlPcTlJ' \
-I "https://yourserver.mobadai.jp/services/api2/yourcode/search/custom/json/SAMPLE/"
HTTP/1.1 200 OK
Date: Sun, 24 Feb 2019 23:48:58 GMT
Server: Apache
Vary: Authorization
X-MobadaiApi-Authenticated: true
Content-Length: *****
:

httpsのSSL証明書†

httpsのSSL証明書には、Let's Encryptを使用する。発行者の署名を確認する必要がある場合には、Let's Encrypt のページからca-certificateを取得できる。

APIへのアクセス†

使用可能なメソッド†

メソッドはGETを使用する。

必須のリクエストヘッダ†

以下のリクエストヘッダは必ず送出しなければならない。

Host: (アクセスするAPIのホスト名)

アクセストークンによる認証を用いる場合、以下のリクエストヘッダは必ず送出しなければならない。

Authorization: (type) (credentials)

文字コード†

APIで使用する文字コードはUTF-8とする。

ハッシュ値†

API中でのハッシュ値の表記は、半角英数0-9a-fを用い、文字列とする。

例: dc7faf3c5cd4a3d5e67a6c53ac919667d748969c

オブジェクトID†

API中でのオブジェクトIDの表記は、プレフィックスは"FO"、以降は半角英数0-9a-fを用い、文字列とする。

例: FO31e1a7b94566d0586903a90a

日付†

日付の書式は次の通りとし、タイムゾーンはJSTを用いる。

"YYYY/MM/DD"
YYYY: 4桁で表記する西暦
MM: 2桁で表記する月(01-12)
DD: 2桁で表記する日(01-31)

日付時刻†

日付時刻の書式は次の通りとし、タイムゾーンはJSTを用いる。

"YYYY/MM/DD hh:mm:ss"
YYYY: 4桁で表記する西暦
MM: 2桁で表記する月(01-12)
DD: 2桁で表記する日(01-31)
hh: 2桁で表記する時(00-23)
mm: 2桁で表記する分(00-59)
ss: 2桁で表記する秒(00-59)

検索文字列ルール†

• 英字・数字は半角を用いる（全角英数字は使用されない）
• カナは全角を用いる（半角カナは使用されない）
• 英文字は大文字を用いる（英小文字は使用されない）
• 次の半角記号は用いない

  <>?_,./\;:][+*}{`~=^-)('%$#"!&

• 次の全角記号、全角機種依存文字は用いない

  〇○◇□△▽☆●◆■▲▼★◎◯♂♀〒（）
  〔〕［］｛｝〈〉《》「」『』【】‘’“”
  →←↑↓⇒⇔…‥、。，．・：；？！゛゜´
  ｀¨＾ヽヾゝゞ〃°′″￥＄￠￡％‰℃Å＋
  －±×÷＝≒≠≦≧＜＞≪≫∞∽∝∴∵∈∋
  ⊆⊇⊂⊃∪∩∧∨￢∀∃∠⊥⌒∂∇≡√∫∬
  ─│┌┐┘└├┬┤┴┼━┃┏┓┛┗┣┳┫
  ┻╋┠┯┨┷┿┝┰┥┸╂＃＆＊＠§※〓♯
  ♭♪†‡¶仝～￣＿―‐∥｜／＼
  №㏍℡㊤㊥㊦㊧㊨㈱㈲㈹㍾㍽㍼㍻㍉㎜㎝㎞㎎
  ㎏㏄㍉㌔㌢㍍㌘㌧㌃㌶㍑㍗㌍㌦㌣㌫㍊㌻①②
  ③④⑤⑥⑦⑧⑨⑩⑪⑫⑬⑭⑮⑯⑰⑱⑲⑳ⅠⅡ
  ⅢⅣⅤⅥⅦⅧⅨⅩ

• 絵文字は用いない

返値†

HTTPレスポンスコード†

エラー時等、アクセスの条件、状態に応じて、返却されるHTTPレスポンスコードは以下の通り。

IPアドレス制限によってアクセスが拒否されている場合†

IPアドレス制限によってアクセスが拒否されている場合は、HTTPレスポンスコード403が返却される。

例:
$ curl -I "https://apiserver-mycode.mobadai.jp/services/api2/mycode/search/custom/json/カレー/0/50/"
HTTP/1.1 403 Forbidden
Date: Wed, 09 Dec 2020 20:51:11 GMT
Server: Apache
Content-Type: text/html; charset=iso-8859-1

アクセストークンによってアクセスが拒否されている場合†

アクセストークンによってアクセスが拒否されている場合は、HTTPレスポンスコード401が返却される。

例:
$ curl -I "https://apiserver-mycode.mobadai.jp/services/api2/mycode/search/custom/json/カレー/0/50/"
HTTP/1.0 401 Unauthorized
Date: Wed, 09 Dec 2020 23:24:28 GMT
Server: Apache

アクセスしているURLまたはアクセスコードが間違っている†

アクセスしているURL、アクセスコード、フォーマットが誤っている場合は、HTTPレスポンスコード404が返却される。

例:
$ curl -I "https://apiserver-mycode.mobadai.jp/service/api2/mycode/search/custom/json/カレー/0/50/"
HTTP/1.1 404 Not Found
Date: Wed, 09 Dec 2020 20:52:22 GMT
Server: Apache
Content-Type: text/html; charset=iso-8859-1

$ curl -I "https://apiserver-mycode.mobadai.jp/services/api2/mycobe/search/custom/json/カレー/0/50/"
HTTP/1.1 404 Not Found
Date: Wed, 09 Dec 2020 20:53:05 GMT
Server: Apache
Content-Type: text/html; charset=iso-8859-1

クエリー文字列の誤り†

クエリー文字列の誤り（禁止文字が含まれる等）の場合は、HTTPレスポンスコード400が返却され、エラー情報を含むjsonがレスポンスボディに返却される。

例:
$ curl -I "https://api-kag-foodsearch2.mobadai.jp/services/api2/foodsearch/search/custom/json/カレー=そば/0/50/"
HTTP/1.1 400 Bad Request
Date: Wed, 09 Dec 2020 20:52:22 GMT
Server: Apache
Content-Length: 23

検索結果が存在しない†

検索した結果の数が０の場合は、HTTPレスポンスコード200かつ結果が空のjsonがレスポンスボディに返却される。

例:
$ curl -I "https://apiserver-mycode.mobadai.jp/services/api2/mycode/search/custom/json/カぬレま８ー/0/50/"
HTTP/1.1 200 OK
Date: Wed, 09 Dec 2020 20:53:58 GMT
Server: Apache
Content-Length: 12

オブジェクトが存在しない†

オブジェクトが存在しない場合は、HTTPレスポンスコード200かつ空のjsonがレスポンスボディに返却される。

例:
$ curl -I "https://apiserver-mycode.mobadai.jp/services/api2/mycode/detail/json/FOf281333b5c6d0a6b329fba5c/"
HTTP/1.1 200 OK
Date: Wed, 09 Dec 2020 22:51:15 GMT
Server: Apache
Content-Length: 2

エラー情報を含むjson†

エラー情報を含むjsonの書式は以下の通り。

{
 "v":1,
 "errcd":"(エラー情報)"
}

疎通確認†

アクセスするAPIサーバーのトップレベルに引数なしでアクセスした場合、動作していればjsonを返却するので、疎通確認に使用できる。IPアドレス制限の状態及びAPIサーバー名の確認が可能である。

例:
$ curl https://apiserver-mycode.mobadai.jp/
{"result":false,"reason":"unknown cmd :","product_version":"20200720-1"}

返却フォーマット†

jsonを使用する。

特殊文字†

返却データ中、特殊文字は参照として表記される。参照は、文字実体参照または数値文字参照が使用される。クライアントでは、適切にデコードすることが望ましい。
参考 文字参照

例

目次

• トップページ
• APIを使用する
• 各APIの詳細
• サンプルソース