IPジオロケーションAPI

GET

IPジオロケーションAPI

curl --request GET \
  --url https://ipgeolocation.cleariflow.com/v1

{
    "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
    }
}

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アドレスと関連する詳細が返されます。

{
    "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
    }
}

リクエストパラメータ

api_key

String

必須

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

ip_address

String

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

fields

String

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

レスポンスパラメータ

APIレスポンスは、汎用的で軽量な JSON形式で返されます。

ip_address

String

ジオロケーションのために送信されたIPアドレスです。

city

String

都市名です。

city_geoname_id

String

都市のgeoname IDです。

region

String

都市が所在する州または県です。

region_iso_code

Char[2]

州または県のISO 3166-2コードです。

region_geoname_id

String

州または県のgeoname IDです。

postal_code

String

ZIPまたは郵便番号です。

country

String

国名です。

country_code

Char[2]

国のISO 3166-1 alpha-2コードです。

country_geoname_id

String

国のgeoname IDです。

country_is_eu

Boolean

国がEUに属する場合に true、そうでない場合に false です。

continent

String

大陸名です。

continent_code

Char[2]

2文字の大陸コード：AF、AS、EU、NA、OC、SA、AN。

continent_geoname_id

String

大陸のgeoname IDです。

longitude

Float

経度の小数値です。

latitude

Float

緯度の小数値です。

security.is_vpn

Boolean

IPが列挙型VPN出口ノードデータベース（IP-to-VPN MMDB）に一致する場合に true です。

security.is_proxy

Boolean

IPがプロキシデータベース（IP-to-VPN MMDB）に一致する場合に true です。

security.vpn_provider

String

MMDBからのVPNサービス名です（例：NordVPN）。is_vpn が false の場合は省略されます。

timezone.name

String

IANAタイムゾーンデータベースからのタイムゾーン名です。

timezone.abbreviation

String

IANAタイムゾーンデータベースからのタイムゾーン略称です。

timezone.gmt_offset

String

グリニッジ標準時（GMT）からのタイムゾーンオフセットです。

timezone.current_time

String

ローカルタイムゾーンの現在時刻です。

timezone.is_dst

Boolean

現在地が現在サマータイム（DST）中の場合に true です。

flag.svg

String

SVG形式の国旗のホスト版へのリンクです。

flag.png

String

PNG形式の国旗のホスト版へのリンクです。

flag.emoji

String

絵文字としての国旗です。

flag.unicode

String

Unicode形式の国旗です。

currency.currency_name

String

通貨名です。

currency.currency_code

String

ISO 4217形式の通貨コードです。

connection.connection_type

String

ASN組織名から推測されます（例：Cellular、Cable/DSL、Corporate、Cloud、Hosting）。VPNとプロキシはここではなく security で報告されます。

connection.autonomous_system_number

Uint32

自律システム番号です。

connection.autonomous_system_organization

String

自律システム組織名です。

connection.isp_name

String

インターネットサービスプロバイダー（ISP）名です。

connection.organization_name

String

組織名です。

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

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

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

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

{
    "city": "Vienna",
    "country": "Austria"
}

ユースケース

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

IPアドレスからジオロケーションをリクエストするには、以下のテンプレートに固有のAPIキーを含めるだけです。リクエストを行うために訪問者のIPを知る必要はありません。

$.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 で表示できます。

国名	国コード
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クレジットがアカウントから差し引かれます。

はじめにCleariflowの為替レートAPIは、洗練されたモダンなRESTful JSONインターフェースを通じてリアルタイムの通貨換算機能を提供し、80以上のグローバル通貨のライブレートと即時換算をサポートします。

IPジオロケーションAPI

curl --request GET \
  --url https://ipgeolocation.cleariflow.com/v1

{
    "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
    }
}

​はじめに

​RESTアーキテクチャ

​HTTPSセキュリティ

​APIバージョン管理

​APIキーによる認証

​ベースURL

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

​リクエストパラメータ

​レスポンスパラメータ

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

​ユースケース

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

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

​国コード

​その他の注意事項

はじめに

RESTアーキテクチャ

HTTPSセキュリティ

APIバージョン管理

APIキーによる認証

ベースURL

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

リクエストパラメータ

レスポンスパラメータ

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

ユースケース

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

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

国コード

その他の注意事項