{
  "openapi": "3.1.0",
  "info": {
    "title": "シルギア 電話番号・市外局番API",
    "version": "1.0.0",
    "description": "登録不要・無料の電話番号・市外局番のAPI。電話番号から正しいハイフンの位置と種類（固定電話・携帯電話・IP電話・フリーダイヤルなど）を返し、固定電話なら市外局番・市内局番・地域（番号区画）・都道府県・番号の範囲を割り当てられた電話会社も返します。総務省「電気通信番号指定状況」（固定電話番号）・「市外局番の一覧」を加工して作成（公共データ利用規約 第1.0版）。in_use は番号の範囲（先頭6桁）が割り当て済みかどうかで、その番号をだれかが使っているかは表しません。説明: https://api.shirugear.com/tel/ 。v1 の中では項目を足すことはあっても、名前や意味は変えません（知らない項目は無視してください）。",
    "termsOfService": "https://api.shirugear.com/terms/",
    "contact": {
      "name": "アナライズギア株式会社（シルギア）",
      "url": "https://shirugear.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://api.shirugear.com"
    }
  ],
  "paths": {
    "/tel/v1/{number}.json": {
      "get": {
        "summary": "電話番号1つ（ハイフン付きの形・種類・固定電話なら地域）",
        "operationId": "getTel",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "0 から始まる半角数字の電話番号。ハイフンは付けても付けなくてもよい（取り除いてから判定する）。固定電話・0120・0570・0180・0990 は10桁、携帯電話（070・080・090）・050・0800・020・060 は11桁",
            "schema": {
              "type": "string",
              "pattern": "^[0-9-]+$",
              "examples": [
                "0123456789",
                "04-7123-4567",
                "09012345678"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "判定できた（固定電話は総務省の指定状況の表に先頭6桁があるもの。未使用の範囲を含む）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TelResponse"
                }
              }
            }
          },
          "400": {
            "description": "形が正しくない・桁数が種類と合わない（invalid_number）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "固定電話の番号で、先頭6桁が総務省の指定状況の表に無い（number_not_found）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tel/v1/areas.json": {
      "get": {
        "summary": "市外局番の一覧",
        "operationId": "getTelAreas",
        "responses": {
          "200": {
            "description": "一覧",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AreasResponse"
                }
              }
            }
          }
        }
      }
    },
    "/tel/v1/prefixes.json": {
      "get": {
        "summary": "固定電話の先頭6桁の表（全件）",
        "operationId": "getTelPrefixes",
        "responses": {
          "200": {
            "description": "全件",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrefixesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/tel/v1/meta.json": {
      "get": {
        "summary": "データの版・出典・件数",
        "operationId": "getTelMeta",
        "responses": {
          "200": {
            "description": "版と件数",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetaResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Type": {
        "type": "string",
        "enum": [
          "fixed",
          "mobile",
          "ip",
          "freedial",
          "navidial",
          "teledome",
          "premium",
          "m2m",
          "fmc"
        ],
        "description": "fixed=固定電話 / mobile=携帯電話（070・080・090）/ ip=IP電話（050）/ freedial=フリーダイヤル（0120・0800）/ navidial=ナビダイヤル（0570）/ teledome=テレドーム（0180）/ premium=情報料代理徴収（0990）/ m2m=M2M等専用番号（020）/ fmc=FMC（060）。値が増えることがある"
      },
      "Area": {
        "type": "object",
        "required": [
          "section_code",
          "name",
          "prefectures"
        ],
        "properties": {
          "section_code": {
            "type": "string",
            "description": "番号区画コード"
          },
          "name": {
            "type": "string",
            "description": "番号区画の名前（総務省「市外局番の一覧」の書き方そのまま）"
          },
          "prefectures": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "その番号区画にかかる都道府県"
          }
        }
      },
      "TelResponse": {
        "type": "object",
        "required": [
          "number",
          "formatted",
          "type",
          "type_name",
          "area_code",
          "local_code",
          "subscriber",
          "area",
          "carrier",
          "in_use",
          "data_version"
        ],
        "properties": {
          "number": {
            "type": "string",
            "pattern": "^0[1-9][0-9]{8,9}$",
            "description": "ハイフンを取り除いた電話番号"
          },
          "formatted": {
            "type": "string",
            "description": "ハイフン付きの電話番号",
            "examples": [
              "0123-45-6789",
              "090-1234-5678"
            ]
          },
          "type": {
            "$ref": "#/components/schemas/Type"
          },
          "type_name": {
            "type": "string",
            "description": "種類の日本語（言い回しが変わることがある）"
          },
          "area_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "市外局番（頭の 0 を含む）。固定電話以外は null"
          },
          "local_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "市内局番。固定電話以外は null"
          },
          "subscriber": {
            "type": [
              "string",
              "null"
            ],
            "description": "加入者番号（最後の4桁）。固定電話以外は null"
          },
          "area": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Area"
              },
              {
                "type": "null"
              }
            ],
            "description": "地域（番号区画）。固定電話以外は null"
          },
          "carrier": {
            "type": [
              "string",
              "null"
            ],
            "description": "総務省がその番号の範囲（先頭6桁）を割り当てた電話会社。番号ポータビリティで今の会社と違うことがある。未使用の範囲と固定電話以外は null"
          },
          "in_use": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "総務省の指定状況でその範囲が「使用中」なら true、「未使用」なら false。固定電話以外は null。その番号をだれかが使っているかは表さない"
          },
          "data_version": {
            "type": "string",
            "format": "date"
          }
        }
      },
      "Section": {
        "type": "object",
        "required": [
          "code",
          "name",
          "prefectures"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "番号区画コード（TelResponse の area.section_code と同じ）"
          },
          "name": {
            "type": "string"
          },
          "prefectures": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "AreaCode": {
        "type": "object",
        "required": [
          "area_code",
          "local_code_digits",
          "prefectures",
          "sections"
        ],
        "properties": {
          "area_code": {
            "type": "string",
            "pattern": "^0[1-9][0-9]{0,3}$",
            "description": "市外局番（頭の 0 を含む）"
          },
          "local_code_digits": {
            "type": "integer",
            "description": "市内局番の桁数（市外局番と合わせて6桁になる数）"
          },
          "prefectures": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Section"
            }
          }
        }
      },
      "AreasResponse": {
        "type": "object",
        "required": [
          "data_version",
          "count",
          "areas"
        ],
        "properties": {
          "data_version": {
            "type": "string",
            "format": "date"
          },
          "count": {
            "type": "integer"
          },
          "areas": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AreaCode"
            },
            "description": "市外局番の順"
          }
        }
      },
      "PrefixesResponse": {
        "type": "object",
        "required": [
          "data_version",
          "count",
          "fields",
          "prefixes"
        ],
        "properties": {
          "data_version": {
            "type": "string",
            "format": "date"
          },
          "count": {
            "type": "integer"
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "prefixes の値の並び（[\"area_code\", \"section\", \"in_use\"]）"
          },
          "prefixes": {
            "type": "object",
            "description": "先頭6桁 → [市外局番, 番号区画コード, 使用中なら1・未使用なら0]",
            "propertyNames": {
              "pattern": "^0[1-9][0-9]{4}$"
            },
            "additionalProperties": {
              "type": "array",
              "prefixItems": [
                {
                  "type": "string"
                },
                {
                  "type": "string"
                },
                {
                  "type": "integer",
                  "enum": [
                    0,
                    1
                  ]
                }
              ],
              "minItems": 3,
              "maxItems": 3
            }
          }
        }
      },
      "MetaResponse": {
        "type": "object",
        "required": [
          "data_version",
          "built_at",
          "source",
          "license",
          "sources",
          "fetched_at",
          "counts"
        ],
        "properties": {
          "data_version": {
            "type": "string",
            "format": "date",
            "description": "使った総務省の公表のうち、いちばん新しい版"
          },
          "built_at": {
            "type": "string",
            "format": "date-time"
          },
          "source": {
            "type": "string"
          },
          "license": {
            "type": "string"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "url"
              ],
              "properties": {
                "name": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "as_of": {
                  "type": "string",
                  "format": "date"
                },
                "page": {
                  "type": "string"
                }
              }
            }
          },
          "fetched_at": {
            "type": "string",
            "format": "date-time"
          },
          "counts": {
            "type": "object",
            "required": [
              "prefixes",
              "in_use",
              "area_codes",
              "sections"
            ],
            "properties": {
              "prefixes": {
                "type": "integer",
                "description": "固定電話の先頭6桁の数"
              },
              "in_use": {
                "type": "integer",
                "description": "そのうち使用中の数"
              },
              "area_codes": {
                "type": "integer"
              },
              "sections": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "status",
              "code",
              "message"
            ],
            "properties": {
              "status": {
                "type": "integer"
              },
              "code": {
                "type": "string",
                "description": "エラーの種類（固定値）",
                "enum": [
                  "invalid_number",
                  "number_not_found",
                  "not_found",
                  "region_not_allowed",
                  "method_not_allowed"
                ]
              },
              "message": {
                "type": "string",
                "description": "日本語の説明"
              }
            }
          }
        }
      }
    }
  }
}
