> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IPジオロケーションAPI

> CleariflowのIPジオロケーションAPIは、190か国以上のIPアドレスの位置情報と詳細データを特定する、高速・効率的・モダンなRESTful JSON APIです。

APIの操作は非常にシンプルです。APIキーとIPアドレスを指定するだけで、郵便番号、都市名、地域情報、国の詳細、正確な緯度/経度座標を含む包括的な位置データが返されます。

## はじめに

### RESTアーキテクチャ

CleariflowのすべてのAPIと同様、IPジオロケーションAPIはRESTの原則に従います。予測可能なリソース指向のURLを採用し、エラー表示にHTTPステータスコードを使用します。

### HTTPSセキュリティ

IPジオロケーションAPIとのすべての通信は、TLS 1.2以上のプロトコルで保護する必要があります。

### APIバージョン管理

CleariflowのすべてのAPIにはバージョン管理が組み込まれています。IPジオロケーションAPIは現在バージョン1で稼働しています。

### APIキーによる認証

APIキーは、Cleariflow IPジオロケーションAPIにアクセスするための固有の認証情報です。Cleariflowの各APIには固有のAPIキーが必要であり、IPジオロケーションとメール検証APIなど異なるサービスでは別々のキーが必要です。リクエストを認証するには、ベースURLにAPIキーを付加してください。

### ベースURL

```
https://ipgeolocation.cleariflow.com/v1/
```

### ジオロケーションエンドポイント

Cleariflow IPジオロケーションAPIでは、固有のAPIキーのみが必要で、リクエスト元クライアントのIPアドレスを自動的に検出します。または、"ip\_address" パラメータを含めて分析対象の特定のIPを指定できます。

```
https://ipgeolocation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& ip_address = 94.198.41.118 (optional)
```

これは成功したリクエストを表し、以下にIPアドレスと関連する詳細が返されます。

<ResponseExample>
  ```json theme={"system"}
  {
      "ip_address": "80.255.13.30",
      "city": null,
      "city_geoname_id": null,
      "region": null,
      "region_iso_code": null,
      "region_geoname_id": null,
      "postal_code": null,
      "country": "Germany",
      "country_code": "DE",
      "country_geoname_id": 2921044,
      "country_is_eu": true,
      "continent": "Europe",
      "continent_code": "EU",
      "continent_geoname_id": 6255148,
      "longitude": 9.491,
      "latitude": 51.2993,
      "security": {
          "is_vpn": true,
          "is_proxy": false,
          "vpn_provider": "NordVPN"
      },
      "timezone": {
          "name": "Europe/Berlin",
          "abbreviation": "CEST",
          "gmt_offset": 2,
          "current_time": "21:21:22",
          "is_dst": true
      },
      "flag": {
          "emoji": "🇩🇪",
          "unicode": "U+1F1E9 U+1F1EA",
          "png": "https://static.cleariflow.com/country-flags/DE_flag.png",
          "svg": "https://static.cleariflow.com/country-flags/DE_flag.svg"
      },
      "currency": {
          "currency_name": "Euros",
          "currency_code": "EUR"
      },
      "connection": {
          "autonomous_system_number": 201011,
          "autonomous_system_organization": "Core-Backbone GmbH",
          "connection_type": null,
          "isp_name": null,
          "organization_name": null
      }
  }
  ```
</ResponseExample>

### リクエストパラメータ

<ParamField query="api_key" type="String" required>
  固有のAPIキーです。各ユーザーはCleariflowの各APIごとに固有のAPIキーを持っているため、IPジオロケーションAPIのキーはメール検証APIなどでは動作しません。
</ParamField>

<ParamField query="ip_address" type="String">
  ジオロケーション対象のIPアドレスです。IPv4とIPv6の両方をサポートしています。このパラメータを空白のままにすると、リクエストが送信されたIPアドレスをジオロケーションします。
</ParamField>

<ParamField query="fields" type="String">
  返す **トップレベル** キーのカンマ区切りリストです（例：`?fields=country,security`）。VPN/プロキシフラグを含めるには `security` を使用します。オブジェクト全体が返されます（存在する場合は `is_vpn`、`is_proxy`、`vpn_provider`）。`is_vpn` 単体のようなネストされたキーはサポートされていません。
</ParamField>

### レスポンスパラメータ

APIレスポンスは、汎用的で軽量な [JSON形式](https://www.json.org/json-en.html) で返されます。

<ResponseField name="ip_address" type="String">
  ジオロケーションのために送信されたIPアドレスです。
</ResponseField>

<ResponseField name="city" type="String">
  都市名です。
</ResponseField>

<ResponseField name="city_geoname_id" type="String">
  都市のgeoname IDです。
</ResponseField>

<ResponseField name="region" type="String">
  都市が所在する州または県です。
</ResponseField>

<ResponseField name="region_iso_code" type="Char[2]">
  州または県のISO 3166-2コードです。
</ResponseField>

<ResponseField name="region_geoname_id" type="String">
  州または県のgeoname IDです。
</ResponseField>

<ResponseField name="postal_code" type="String">
  ZIPまたは郵便番号です。
</ResponseField>

<ResponseField name="country" type="String">
  国名です。
</ResponseField>

<ResponseField name="country_code" type="Char[2]">
  国のISO 3166-1 alpha-2コードです。
</ResponseField>

<ResponseField name="country_geoname_id" type="String">
  国のgeoname IDです。
</ResponseField>

<ResponseField name="country_is_eu" type="Boolean">
  国がEUに属する場合に true、そうでない場合に false です。
</ResponseField>

<ResponseField name="continent" type="String">
  大陸名です。
</ResponseField>

<ResponseField name="continent_code" type="Char[2]">
  2文字の大陸コード：AF、AS、EU、NA、OC、SA、AN。
</ResponseField>

<ResponseField name="continent_geoname_id" type="String">
  大陸のgeoname IDです。
</ResponseField>

<ResponseField name="longitude" type="Float">
  経度の小数値です。
</ResponseField>

<ResponseField name="latitude" type="Float">
  緯度の小数値です。
</ResponseField>

<ResponseField name="security.is_vpn" type="Boolean">
  IPが列挙型VPN出口ノードデータベース（IP-to-VPN MMDB）に一致する場合に `true` です。
</ResponseField>

<ResponseField name="security.is_proxy" type="Boolean">
  IPがプロキシデータベース（IP-to-VPN MMDB）に一致する場合に `true` です。
</ResponseField>

<ResponseField name="security.vpn_provider" type="String">
  MMDBからのVPNサービス名です（例：`NordVPN`）。`is_vpn` が `false` の場合は省略されます。
</ResponseField>

<ResponseField name="timezone.name" type="String">
  IANAタイムゾーンデータベースからのタイムゾーン名です。
</ResponseField>

<ResponseField name="timezone.abbreviation" type="String">
  IANAタイムゾーンデータベースからのタイムゾーン略称です。
</ResponseField>

<ResponseField name="timezone.gmt_offset" type="String">
  グリニッジ標準時（GMT）からのタイムゾーンオフセットです。
</ResponseField>

<ResponseField name="timezone.current_time" type="String">
  ローカルタイムゾーンの現在時刻です。
</ResponseField>

<ResponseField name="timezone.is_dst" type="Boolean">
  現在地が現在サマータイム（DST）中の場合に true です。
</ResponseField>

<ResponseField name="flag.svg" type="String">
  SVG形式の国旗のホスト版へのリンクです。
</ResponseField>

<ResponseField name="flag.png" type="String">
  PNG形式の国旗のホスト版へのリンクです。
</ResponseField>

<ResponseField name="flag.emoji" type="String">
  絵文字としての国旗です。
</ResponseField>

<ResponseField name="flag.unicode" type="String">
  Unicode形式の国旗です。
</ResponseField>

<ResponseField name="currency.currency_name" type="String">
  通貨名です。
</ResponseField>

<ResponseField name="currency.currency_code" type="String">
  ISO 4217形式の通貨コードです。
</ResponseField>

<ResponseField name="connection.connection_type" type="String">
  ASN組織名から推測されます（例：Cellular、Cable/DSL、Corporate、Cloud、Hosting）。VPNとプロキシはここではなく `security` で報告されます。
</ResponseField>

<ResponseField name="connection.autonomous_system_number" type="Uint32">
  自律システム番号です。
</ResponseField>

<ResponseField name="connection.autonomous_system_organization" type="String">
  自律システム組織名です。
</ResponseField>

<ResponseField name="connection.isp_name" type="String">
  インターネットサービスプロバイダー（ISP）名です。
</ResponseField>

<ResponseField name="connection.organization_name" type="String">
  組織名です。
</ResponseField>

### レスポンスフィールドの制限

JSONレスポンスから一部のフィールドのみを受け取ることができます。そのためには、クエリパラメータに fields 値を含め、返したいトップレベルキーのカンマ区切りリストを指定します。

例えば、IPの国と都市のみを取得するリクエストは次のようになります。

```
https://ipgeolocation.cleariflow.com/v1/
    ? api_key = YOUR_API_KEY
    & ip_address = 94.198.41.122
    & fields = country,city
```

レスポンスは次のようになります。

```json theme={"system"}
{
    "city": "Vienna",
    "country": "Austria"
}
```

## ユースケース

### ウェブサイト訪問者のジオロケーション

IPアドレスからジオロケーションをリクエストするには、以下のテンプレートに固有のAPIキーを含めるだけです。

リクエストを行うために訪問者のIPを知る必要はありません。

```javascript theme={"system"}
$.getJSON("https://ipgeolocation.cleariflow.com/v1/?api_key=YOUR_UNIQUE_API_KEY", function(data) {
   console.log(data.ip_address);
   console.log(data.country);
})
```

訪問者からジオロケーションとその他のデータを取得するために必要なのはこれだけです！必須パラメータは固有のAPIキーのみです。

## レスポンスおよびエラーコード

何らかの理由でリクエストが失敗した場合、エラーもJSON形式で返されます。エラーにはエラーコードと説明が含まれ、詳細は以下のとおりです。

| Code | Type                  | Details                                                          |
| ---- | --------------------- | ---------------------------------------------------------------- |
| 200  | OK                    | すべてが想定どおりに動作しました。                                                |
| 204  | OK                    | 送信されたIPの位置データがありません。                                             |
| 400  | Bad request           | 不正なリクエストです。                                                      |
| 401  | Unauthorized          | リクエストが受け付けられませんでした。通常はAPIキーが欠落しているか不正です。                         |
| 422  | Quota reached         | APIクレジット不足のためリクエストが中止されました。（無料プラン）                               |
| 429  | Too many requests     | 許可された秒あたりのリクエスト数に達したためリクエストが中止されました。無料プランでは1秒あたり1リクエストに制限されています。 |
| 500  | Internal server error | サーバー側のエラーによりリクエストを完了できませんでした。                                    |
| 503  | Service unavailable   | サーバーが利用できませんでした。                                                 |

## 国コード

以下はレスポンスで使用される2文字のISO 3166 Alpha 2国コードのリストです。このリストを [CSV](https://docs.google.com/spreadsheets/d/1w4VMneDoL6JW2NaUp2SjTOyvRcD4rlXDI0XpqKS2PeQ/view?usp=sharing) で表示できます。

| 国名                               | 国コード |
| -------------------------------- | ---- |
| Afghanistan                      | AF   |
| Albania                          | AL   |
| Algeria                          | DZ   |
| American Samoa                   | AS   |
| Andorra                          | AD   |
| Angola                           | AO   |
| Anguilla                         | AI   |
| Antigua and Barbuda              | AG   |
| Argentina                        | AR   |
| Armenia                          | AM   |
| Aruba                            | AW   |
| Australia                        | AU   |
| Austria                          | AT   |
| Azerbaijan                       | AZ   |
| Bahrain                          | BH   |
| Bangladesh                       | BD   |
| Barbados                         | BB   |
| Belarus                          | BY   |
| Belgium                          | BE   |
| Belize                           | BZ   |
| Benin                            | BJ   |
| Bermuda                          | BM   |
| Bhutan                           | BT   |
| Bolivia                          | BO   |
| Bosnia and Herzegovina           | BA   |
| Botswana                         | BW   |
| Brazil                           | BR   |
| British Virgin Islands           | VG   |
| Brunei                           | BN   |
| Bulgaria                         | BG   |
| Burkina Faso                     | BF   |
| Burundi                          | BI   |
| Cabo Verde                       | CV   |
| Cambodia                         | KH   |
| Cameroon                         | CM   |
| Canada                           | CA   |
| Cayman Islands                   | KY   |
| Central African Republic         | CF   |
| Chad                             | TD   |
| Chile                            | CL   |
| China                            | CN   |
| Colombia                         | CO   |
| Comoros                          | KM   |
| Congo                            | CG   |
| Congo Democratic Republic        | CD   |
| Cook Islands                     | CK   |
| Costa Rica                       | CR   |
| Cote d'Ivoire                    | CI   |
| Croatia                          | HR   |
| Cuba                             | CU   |
| Curaçao                          | CW   |
| Cyprus                           | CY   |
| Czechia                          | CZ   |
| Denmark                          | DK   |
| Djibouti                         | DJ   |
| Dominica                         | DM   |
| Dominican Republic               | DO   |
| East Timor                       | TL   |
| Ecuador                          | EC   |
| Egypt                            | EG   |
| El Salvador                      | SV   |
| Equatorial Guinea                | GQ   |
| Eritrea                          | ER   |
| Estonia                          | EE   |
| eSwatini                         | SZ   |
| Ethiopia                         | ET   |
| Falkland Islands                 | FK   |
| Faroe Islands                    | FO   |
| Fiji                             | FJ   |
| Finland                          | FI   |
| France                           | FR   |
| French Guiana                    | GF   |
| French Polynesia                 | PF   |
| Gabon                            | GA   |
| Gambia                           | GM   |
| Georgia                          | GE   |
| Germany                          | DE   |
| Ghana                            | GH   |
| Gibraltar                        | GI   |
| Greece                           | GR   |
| Greenland                        | GL   |
| Grenada                          | GD   |
| Guadeloupe                       | GP   |
| Guam                             | GU   |
| Guatemala                        | GT   |
| Guernsey                         | GG   |
| Guinea                           | GN   |
| Guinea-Bissau                    | GW   |
| Guyana                           | GY   |
| Haiti                            | HT   |
| Honduras                         | HN   |
| Hong Kong                        | HK   |
| Hungary                          | HU   |
| Iceland                          | IS   |
| India                            | IN   |
| Indonesia                        | ID   |
| Iran                             | IR   |
| Iraq                             | IQ   |
| Ireland                          | IE   |
| Isle of Man                      | IM   |
| Israel                           | IL   |
| Italy                            | IT   |
| Jamaica                          | JM   |
| Japan                            | JP   |
| Jersey                           | JE   |
| Jordan                           | JO   |
| Kazakhstan                       | KZ   |
| Kenya                            | KE   |
| Kiribati                         | KI   |
| Kosovo                           | XK   |
| Kuwait                           | KW   |
| Kyrgyzstan                       | KG   |
| Laos                             | LA   |
| Latvia                           | LV   |
| Lebanon                          | LB   |
| Lesotho                          | LS   |
| Liberia                          | LR   |
| Libya                            | LY   |
| Liechtenstein                    | LI   |
| Lithuania                        | LT   |
| Luxembourg                       | LU   |
| Macau                            | MO   |
| Madagascar                       | MG   |
| Malawi                           | MW   |
| Malaysia                         | MY   |
| Maldives                         | MV   |
| Mali                             | ML   |
| Malta                            | MT   |
| Marshall Islands                 | MH   |
| Martinique                       | MQ   |
| Mauritania                       | MR   |
| Mauritius                        | MU   |
| Mayotte                          | YT   |
| Mexico                           | MX   |
| Micronesia                       | FM   |
| Moldova                          | MD   |
| Monaco                           | MC   |
| Mongolia                         | MN   |
| Montenegro                       | ME   |
| Montserrat                       | MS   |
| Morocco                          | MA   |
| Mozambique                       | MZ   |
| Myanmar                          | MM   |
| Namibia                          | NA   |
| Nauru                            | NR   |
| Nepal                            | NP   |
| Netherlands                      | NL   |
| New Caledonia                    | NC   |
| New Zealand                      | NZ   |
| Nicaragua                        | NI   |
| Niger                            | NE   |
| Nigeria                          | NG   |
| North Korea                      | KP   |
| North Macedonia                  | MK   |
| Northern Mariana Islands         | MP   |
| Norway                           | NO   |
| Oman                             | OM   |
| Pakistan                         | PK   |
| Palau                            | PW   |
| Panama                           | PA   |
| Papua New Guinea                 | PG   |
| Paraguay                         | PY   |
| Peru                             | PE   |
| Philippines                      | PH   |
| Poland                           | PL   |
| Portugal                         | PT   |
| Puerto Rico                      | PR   |
| Qatar                            | QA   |
| Reunion                          | RE   |
| Romania                          | RO   |
| Russia                           | RU   |
| Rwanda                           | RW   |
| Saint Helena                     | SH   |
| Saint Kitts and Nevis            | KN   |
| Saint Lucia                      | LC   |
| Saint Martin                     | MF   |
| Saint Pierre and Miquelon        | PM   |
| Saint Vincent and the Grenadines | VC   |
| Samoa                            | WS   |
| San Marino                       | SM   |
| Sao Tome and Principe            | ST   |
| Saudi Arabia                     | SA   |
| Senegal                          | SN   |
| Serbia                           | RS   |
| Seychelles                       | SC   |
| Sierra Leone                     | SL   |
| Singapore                        | SG   |
| Sint Maarten                     | SX   |
| Slovakia                         | SK   |
| Slovenia                         | SI   |
| Solomon Islands                  | SB   |
| Somalia                          | SO   |
| South Africa                     | ZA   |
| South Korea                      | KR   |
| South Sudan                      | SS   |
| Spain                            | ES   |
| Sri Lanka                        | LK   |
| St. Barts                        | BL   |
| Sudan                            | SD   |
| Suriname                         | SR   |
| Sweden                           | SE   |
| Switzerland                      | CH   |
| Syria                            | SY   |
| Taiwan                           | TW   |
| Tajikistan                       | TJ   |
| Tanzania                         | TZ   |
| Thailand                         | TH   |
| The Bahamas                      | BS   |
| Togo                             | TG   |
| Tonga                            | TO   |
| Trinidad and Tobago              | TT   |
| Tunisia                          | TN   |
| Turkey                           | TR   |
| Turkmenistan                     | TM   |
| Turks and Caicos Islands         | TC   |
| Tuvalu                           | TV   |
| Uganda                           | UG   |
| Ukraine                          | UA   |
| United Arab Emirates             | AE   |
| United Kingdom                   | GB   |
| United States                    | US   |
| Uruguay                          | UY   |
| US Virgin Islands                | VI   |
| Uzbekistan                       | UZ   |
| Vanuatu                          | VU   |
| Vatican City (Holy See)          | VA   |
| Venezuela                        | VE   |
| Vietnam                          | VN   |
| Wallis and Futuna                | WF   |
| Yemen                            | YE   |
| Zambia                           | ZM   |
| Zimbabwe                         | ZW   |

## その他の注意事項

課金に関する重要な情報：処理するIPアドレスごとに1クレジットを消費します。レスポンスが成功したかどうかに関わらず、リクエスト送信ごとに課金されます。そのため、「fda3346ds」のような無効なIPアドレスを送信しても、1クレジットがアカウントから差し引かれます。