Filterリファレンス | PostcodeJP Docs

条件式のモデル

Filter model

field operator value

pref==東京都
town==市谷*

filter式はquery parameterの値です。URLへ手で連結せず、URLSearchParamsなどでencodeしてください。

URL encoding

const params = new URLSearchParams({
  filter: "pref==東京都;city==新宿区",
  fields: "postcode,pref,city,town",
  limit: "10"
});

const url = new URL("https://apis.postcode-jp.com/api/v6/postcodes");
url.search = params.toString();

公開filter fields

新規integrator向けの公開fieldは31個です。文字列29個、boolean 2個です。

pref
city
town
allAddress
office
postcode
oldPostcode
prefCode
cityCode
hiragana.pref
hiragana.city
hiragana.town
hiragana.office
hiragana.allAddress
halfWidthKana.pref
halfWidthKana.city
halfWidthKana.town
halfWidthKana.office
halfWidthKana.allAddress
fullWidthKana.pref
fullWidthKana.city
fullWidthKana.town
fullWidthKana.office
fullWidthKana.allAddress
english.pref
english.city
english.town
english.office
english.allAddress
generalPostcode — boolean
officePostcode — boolean

locationはfilterできません

locationはresponse fieldとして選択できますが、filter fieldではありません。

Operators

Operator	Meaning
`==`	等しい。stringではwildcardを利用可能
`!=`	等しくない。stringではwildcardを利用可能
`< / =lt=`	より小さい
`<= / =le=`	以下
`> / =gt=`	より大きい
`>= / =ge=`	以上
`=in=`	候補のいずれかに一致
`=out=`	候補のいずれにも一致しない
`=re=`	string field向け正規表現（Advanced）

String matching

Expression	Meaning
`field==value`	wildcardを含まないexact-like match
`field==value*`	prefix match
`field==value`	contains match
`_`	任意の1文字

文字表現や表記揺れによって結果が異なる場合があります。「すべてのUnicode表現で完全に同じ結果になる」とは仮定しないでください。

郵便番号は自動normalizeされません

100-0001、１０００００１、1000001は、filterでは自動的に同じ値へ変換されません。必要な入力補助はAPIへ渡す前に行ってください。

複数条件と優先順位

AND: ; または and
OR: , または or
ANDはORより先に評価されます。
parenthesesでgroupingを明示できます。

Condition examples

pref==東京都;city==新宿区
pref==東京都,city==大阪市
pref==東京都;(city==新宿区,town==市谷*)
postcode=in=(1000001,1600023)

Quoteとescape

spaceやreserved characterを含むvalueはsingle quoteまたはdouble quoteで囲みます。quote内の同じquoteとbackslashはbackslashでescapeします。

Quoted values

office=='Example Main Office'
office=="Example \"Main\" Office"
town=='Backslash \\ value'

通常の値をquoteしても受理されますが、quoteは主にspaceやreserved characterを安全に表現するために使用してください。

nullは特殊なNULL operatorではありません

literal nullは通常の文字列として比較されます。SQL NULLを検索する機能として使用しないでください。

Booleanとregex

Boolean fields

generalPostcodeとofficePostcodeでは、==または!=とtrue/falseだけを使用します。

boolean fieldではrange、IN、OUT、regexを使用できません。不正な組み合わせは400です。

Regex — Advanced

=re=はstring field向けのAdvanced operatorです。basicな正規表現を指定できますが、engine version、engine固有の全機能、完全なnormalize規則、極端に複雑な式のperformanceは公開契約に含みません。

Regex syntax example

town=re=^市谷.*$
english.city=re=^Chiyoda

空のvalue、malformed quote、malformed parentheses、空のIN listは無効です。

Filter examples

Intent	Filter	Semantics
郵便番号	`postcode==1000001`	完全一致
都道府県	`pref==東京都`	都道府県field
市区町村	`city==新宿区`	市区町村field
町域prefix	`town==市谷*`	「市谷」で始まる町域
都道府県 AND 市区町村	`pref==東京都;city==新宿区`	AND
一般または事業所	`generalPostcode==true,officePostcode==true`	OR
English field	`english.pref==Tokyo`	syntax example。dataset内の値は保証しない

これらはgrammarの例です。例示した文字列がすべてのdataset versionに存在することは保証しません。