{
  "openapi": "3.1.0",
  "info": {
    "title": "PhoneLookup number endpoint",
    "version": "1.0.0",
    "summary": "What the national numbering plan says about one phone number.",
    "description": "Free, without a key, from the published numbering plans: validity, territory, line type, the parts of the number, its four formats and the carrier its block was originally allocated to. It cannot say whether a number is in service or which carrier serves it today. Limits: 60 requests a minute and 2,000 a day per address. Published by Epic Grove Ltd.",
    "contact": {
      "name": "Epic Grove Ltd",
      "email": "contact@epicgrove.ltd",
      "url": "https://phonelookup.dev/about"
    }
  },
  "externalDocs": {
    "description": "The endpoint explained, with examples",
    "url": "https://phonelookup.dev/api"
  },
  "servers": [
    {
      "url": "https://phonelookup.dev"
    }
  ],
  "security": [],
  "paths": {
    "/v1/number": {
      "get": {
        "operationId": "checkNumber",
        "summary": "Check a number",
        "description": "Pass the number in international format (+ and the country code) or in national format with region.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "The number, as typed: +447400123456, +44 7400 123456, 07400 123456 (with region=GB).",
            "schema": {
              "type": "string",
              "maxLength": 40
            },
            "example": "+447400123456"
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "description": "ISO 3166-1 alpha-2 code used to read a number written without its country code. Ignored when q starts with +.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            },
            "example": "GB"
          }
        ],
        "responses": {
          "200": {
            "description": "What the numbering plan says about the number. A number the plan does not allocate is still a 200, with valid false and a reason.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NumberResult"
                },
                "example": {
                  "input": "+447400123456",
                  "valid": true,
                  "possible": true,
                  "reason": null,
                  "region": "GB",
                  "callingCode": 44,
                  "e164": "+447400123456",
                  "type": "Mobile",
                  "parts": {
                    "countryCode": "+44",
                    "destinationCode": "7400",
                    "destinationKind": "network code",
                    "subscriber": "123456"
                  },
                  "formats": {
                    "e164": "+447400123456",
                    "international": "+44 7400 123456",
                    "national": "07400 123456",
                    "rfc3966": "tel:+44-7400-123456"
                  },
                  "carrier": "Three",
                  "nanp": null,
                  "references": [
                    {
                      "authority": "Ofcom",
                      "title": "National Telephone Numbering Plan",
                      "url": "https://www.ofcom.org.uk/phones-and-broadband/phone-numbers/numbering"
                    },
                    {
                      "authority": "ITU",
                      "title": "National numbering plan: United Kingdom",
                      "url": "https://www.itu.int/oth/T02020000DD/en"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "q is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "More than 60 requests a minute or 2,000 a day from one address.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests from this address; try again in a minute."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/{number}": {
      "get": {
        "operationId": "checkNumberPath",
        "summary": "Check a number from a terminal",
        "description": "The number as the path (curl https://phonelookup.dev/+14155552671). curl, HTTPie and Wget, or any client sending Accept: application/json, get the same JSON as /v1/number, pretty-printed; a browser is redirected to the checker on the home page.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Digits with an optional leading + (spaces, dots, dashes and brackets allowed), at least six characters.",
            "schema": {
              "type": "string",
              "pattern": "^\\+?[0-9][0-9 ().-]{5,}$"
            },
            "example": "+14155552671"
          }
        ],
        "responses": {
          "200": {
            "description": "What the numbering plan says about the number. A number the plan does not allocate is still a 200, with valid false and a reason.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NumberResult"
                },
                "example": {
                  "input": "+447400123456",
                  "valid": true,
                  "possible": true,
                  "reason": null,
                  "region": "GB",
                  "callingCode": 44,
                  "e164": "+447400123456",
                  "type": "Mobile",
                  "parts": {
                    "countryCode": "+44",
                    "destinationCode": "7400",
                    "destinationKind": "network code",
                    "subscriber": "123456"
                  },
                  "formats": {
                    "e164": "+447400123456",
                    "international": "+44 7400 123456",
                    "national": "07400 123456",
                    "rfc3966": "tel:+44-7400-123456"
                  },
                  "carrier": "Three",
                  "nanp": null,
                  "references": [
                    {
                      "authority": "Ofcom",
                      "title": "National Telephone Numbering Plan",
                      "url": "https://www.ofcom.org.uk/phones-and-broadband/phone-numbers/numbering"
                    },
                    {
                      "authority": "ITU",
                      "title": "National numbering plan: United Kingdom",
                      "url": "https://www.itu.int/oth/T02020000DD/en"
                    }
                  ]
                }
              }
            }
          },
          "302": {
            "description": "A browser: redirected to /?q=<number>."
          },
          "429": {
            "description": "More than 60 requests a minute or 2,000 a day from one address.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests from this address; try again in a minute."
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "NumberResult": {
        "type": "object",
        "required": [
          "input",
          "valid",
          "possible",
          "references"
        ],
        "properties": {
          "input": {
            "type": "string",
            "description": "The number as received, trimmed (at most 40 characters)."
          },
          "valid": {
            "type": "boolean",
            "description": "True when the number falls in a range the numbering plan allocates."
          },
          "possible": {
            "type": "boolean",
            "description": "True when its length is one the plan allows, valid or not."
          },
          "reason": {
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "not_a_number",
                  "invalid_for_region"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Why it is not valid: not_a_number (unreadable) or invalid_for_region. Null when valid."
          },
          "region": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 3166-1 alpha-2 code of the territory whose plan the number belongs to."
          },
          "callingCode": {
            "oneOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "The country calling code (ITU-T E.164), without the +."
          },
          "e164": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The number in E.164: +, country code, national significant number."
          },
          "type": {
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "Mobile",
                  "Fixed line",
                  "Fixed line or mobile",
                  "Toll-free",
                  "VoIP",
                  "Premium-rate",
                  "Shared cost",
                  "Personal number",
                  "Pager",
                  "UAN",
                  "Voicemail",
                  "Unknown"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "The line type of its range: Mobile, Fixed line, Fixed line or mobile, Toll-free, VoIP, Premium-rate, Shared cost, Personal number, Pager, UAN, Voicemail, Unknown. Null when not valid."
          },
          "parts": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "countryCode",
                  "subscriber"
                ],
                "properties": {
                  "countryCode": {
                    "type": "string",
                    "examples": [
                      "+44"
                    ]
                  },
                  "destinationCode": {
                    "oneOf": [
                      {
                        "type": "string",
                        "examples": [
                          "7400"
                        ]
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "destinationKind": {
                    "oneOf": [
                      {
                        "type": "string",
                        "enum": [
                          "area code",
                          "network code"
                        ]
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "subscriber": {
                    "type": "string",
                    "examples": [
                      "123456"
                    ]
                  }
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "countryCode, destinationCode (the area or network code, where the plan has one), destinationKind (\"area code\" or \"network code\"), subscriber."
          },
          "formats": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "e164",
                  "international",
                  "national",
                  "rfc3966"
                ],
                "properties": {
                  "e164": {
                    "type": "string",
                    "examples": [
                      "+447400123456"
                    ]
                  },
                  "international": {
                    "type": "string",
                    "examples": [
                      "+44 7400 123456"
                    ]
                  },
                  "national": {
                    "type": "string",
                    "examples": [
                      "07400 123456"
                    ]
                  },
                  "rfc3966": {
                    "type": "string",
                    "examples": [
                      "tel:+44-7400-123456"
                    ]
                  }
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "e164, international, national and rfc3966 (the tel: URI)."
          },
          "carrier": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The carrier the number's block was originally allocated to, where on record. Not necessarily the carrier serving it today (number portability)."
          },
          "nanp": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "npa",
                  "nxx",
                  "state",
                  "lineType"
                ],
                "properties": {
                  "npa": {
                    "type": "string",
                    "examples": [
                      "415"
                    ]
                  },
                  "nxx": {
                    "type": "string",
                    "examples": [
                      "555"
                    ]
                  },
                  "state": {
                    "type": "string",
                    "examples": [
                      "CA"
                    ]
                  },
                  "lineType": {
                    "type": "string",
                    "enum": [
                      "mobile",
                      "fixed_line",
                      "voip",
                      "unknown"
                    ]
                  }
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "For +1 numbers of the United States and Canada: npa (area code), nxx (central office code), state or province, and the lineType the exchange was allocated as (mobile, fixed_line, voip, unknown)."
          },
          "references": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "authority",
                "title",
                "url"
              ],
              "properties": {
                "authority": {
                  "type": "string",
                  "examples": [
                    "Ofcom"
                  ]
                },
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            },
            "description": "The authorities for the plan: the regulator where on record and the plan as notified to the ITU, each with authority, title and url."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "invalid_request",
                  "rate_limited",
                  "not_found"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}