{"openapi":"3.0.2","info":{"title":"IPstack API","version":"1.0.0","description":"IPstack offers a powerful, real-time IP to geolocation API capable of looking up accurate location data and assessing security threats originating from risky IP addresses. Results are delivered within milliseconds in JSON or XML format."},"servers":[{"url":"https://api.ipstack.com","description":"Main API server"}],"security":[],"paths":{"/check":{"get":{"summary":"Requester IP Lookup","operationId":"lookupRequesterIp","parameters":[{"name":"access_key","in":"query","required":true,"description":"Your unique API access key used to authenticate requests.","schema":{"type":"string"}},{"required":false,"schema":{"title":"Fields","type":"string"},"name":"fields","in":"query","description":"Specify which response fields to return (e.g. `country_code`, `main`) to reduce bandwidth and speed up responses."},{"required":false,"schema":{"title":"Hostname","type":"integer","default":0,"enum":[0,1]},"name":"hostname","in":"query","description":"Set to `1` to enable Hostname Lookup."},{"required":false,"schema":{"title":"Security","type":"integer","default":0,"enum":[0,1]},"name":"security","in":"query","description":"Enable advanced security insights like proxy, crawler, Tor detection, threat levels, and anonymizer status."},{"required":false,"schema":{"title":"Language","type":"string","default":"en"},"name":"language","in":"query","description":"Return response data in a specific language using a 2-letter language code."},{"required":false,"schema":{"title":"Callback","type":"string"},"name":"callback","in":"query","description":"Wrap the JSON response inside a JavaScript function for JSONP support."},{"required":false,"schema":{"title":"Output","type":"string","default":"json","enum":["json","xml"]},"name":"output","in":"query","description":"Set to `json` or `xml` to choose between output formats."}],"responses":{"200":{"description":"Successful lookup — geolocation, timezone, currency, connection and security data for the requesting IP address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseObject"},"example":{"ip":"134.201.250.155","type":"ipv4","continent_code":"NA","continent_name":"North America","country_code":"US","country_name":"United States","region_code":"CA","region_name":"California","city":"Los Angeles","zip":"90013","latitude":34.0453,"longitude":-118.2413,"location":{"geoname_id":5368361,"capital":"Washington D.C.","languages":[{"code":"en","name":"English","native":"English"}],"country_flag":"https://assets.ipstack.com/flags/us.svg","country_flag_emoji":"\uD83C\uDDFA\uD83C\uDDF8","country_flag_emoji_unicode":"U+1F1FA U+1F1F8","calling_code":"1","is_eu":false}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"$ref":"#/components/responses/RateLimitReached"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Maintenance"}},"description":"The IPstack API also offers a separate API endpoint capable of detecting the IP address which the current API request is coming from. In order to use this endpoint, simply append `check` to the API's base URL and specify your preferred optional parameters."}},"/{ip_addresses}":{"get":{"summary":"Standard / Bulk Lookup","operationId":"bulkLookup","parameters":[{"required":true,"schema":{"title":"Ip Addresses","type":"string"},"name":"ip_addresses","in":"path"},{"name":"access_key","in":"query","required":true,"description":"Your unique API access key used to authenticate requests.","schema":{"type":"string"}},{"required":false,"schema":{"title":"Fields","type":"string"},"name":"fields","in":"query","description":"Specify which response fields to return (e.g. `country_code`, `main`) to reduce bandwidth and speed up responses."},{"required":false,"schema":{"title":"Hostname","type":"integer","default":0,"enum":[0,1]},"name":"hostname","in":"query","description":"Set to `1` to enable Hostname Lookup."},{"required":false,"schema":{"title":"Security","type":"integer","default":0,"enum":[0,1]},"name":"security","in":"query","description":"Enable advanced security insights like proxy, crawler, Tor detection, threat levels, and anonymizer status."},{"required":false,"schema":{"title":"Language","type":"string","default":"en"},"name":"language","in":"query","description":"Return response data in a specific language using a 2-letter language code."},{"required":false,"schema":{"title":"Callback","type":"string"},"name":"callback","in":"query","description":"Wrap the JSON response inside a JavaScript function for JSONP support."},{"required":false,"schema":{"title":"Output","type":"string","default":"json","enum":["json","xml"]},"name":"output","in":"query","description":"Set to `json` or `xml` to choose between output formats."}],"responses":{"200":{"description":"Successful lookup. Returns a single result object for one IP, or an array of result objects for a comma-separated (bulk) request.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ResponseObject"},{"type":"array","items":{"$ref":"#/components/schemas/ResponseObject"}}]},"example":{"ip":"134.201.250.155","type":"ipv4","continent_code":"NA","continent_name":"North America","country_code":"US","country_name":"United States","region_code":"CA","region_name":"California","city":"Los Angeles","zip":"90013","latitude":34.0453,"longitude":-118.2413,"location":{"geoname_id":5368361,"capital":"Washington D.C.","languages":[{"code":"en","name":"English","native":"English"}],"country_flag":"https://assets.ipstack.com/flags/us.svg","country_flag_emoji":"\uD83C\uDDFA\uD83C\uDDF8","country_flag_emoji_unicode":"U+1F1FA U+1F1F8","calling_code":"1","is_eu":false}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"$ref":"#/components/responses/RateLimitReached"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Maintenance"}},"description":"Look up a single IPv4/IPv6 address, or several at once by appending a comma-separated list (up to 50) of IP addresses to the API's base URL. A single address returns one result object; multiple addresses return an array of result objects."}}},"components":{"schemas":{"ApiError":{"type":"object","description":"Standard apilayer error envelope, shared by every error response.","required":["success","error"],"properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","required":["code","type"],"properties":{"code":{"type":"integer","description":"apilayer numeric error code (the code the API returns in the body, e.g. 101 for an invalid access key — NOT the HTTP status).","example":101},"type":{"type":"string","description":"Machine-readable error type.","example":"invalid_access_key"},"info":{"type":"string","description":"Human-readable error detail.","example":"You have not supplied a valid API Access Key. [Technical Support: support@apilayer.com]"}}}}},"HTTPValidationError":{"title":"HTTPValidationError","type":"object","properties":{"detail":{"title":"Detail","type":"array","items":{"$ref":"#/components/schemas/ValidationError"}}}},"ValidationError":{"title":"ValidationError","required":["loc","msg","type"],"type":"object","properties":{"loc":{"title":"Location","type":"array","items":{"type":"string"}},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}}},"ResponseObject":{"title":"ResponseObject","type":"object","properties":{"ip":{"title":"Ip","anyOf":[{"type":"string","format":"ipv4"},{"type":"string","format":"ipv6"}]},"hostname":{"title":"Hostname","type":"string"},"type":{"title":"Type","type":"string"},"continent_code":{"title":"Continent Code","type":"string"},"continent_name":{"title":"Continent Name","type":"string"},"country_code":{"title":"Country Code","type":"string"},"country_name":{"title":"Country Name","type":"string"},"region_code":{"title":"Region Code","type":"string"},"region_name":{"title":"Region Name","type":"string"},"city":{"title":"City","type":"string"},"zip":{"title":"Zip","type":"string"},"latitude":{"title":"Latitude","default":0,"type":"number"},"longitude":{"title":"Longitude","default":0,"type":"number"},"msa":{"title":"Msa","type":"string"},"dma":{"title":"Dma","type":"string"},"radius":{"title":"Radius","type":"string"},"ip_routing_type":{"title":"Ip Routing Type","type":"string"},"connection_type":{"title":"Connection Type","type":"string"},"location":{"$ref":"#/components/schemas/Location"},"time_zone":{"$ref":"#/components/schemas/TimeZone"},"currency":{"$ref":"#/components/schemas/Currency"},"connection":{"$ref":"#/components/schemas/Connection"},"security":{"$ref":"#/components/schemas/Security"}}},"Language":{"title":"Language","type":"object","properties":{"code":{"title":"Code","type":"string"},"name":{"title":"Name","type":"string"},"native":{"title":"Native","type":"string"}}},"Location":{"title":"Location","type":"object","properties":{"geoname_id":{"title":"Geoname Id","type":"integer"},"capital":{"title":"Capital","type":"string"},"languages":{"title":"Languages","type":"array","items":{"$ref":"#/components/schemas/Language"}},"country_flag":{"title":"Country Flag","minLength":1,"maxLength":2083,"format":"uri","type":"string"},"country_flag_emoji":{"title":"Country Flag Emoji","type":"string"},"country_flag_emoji_unicode":{"title":"Country Flag Emoji Unicode","type":"string"},"calling_code":{"title":"Calling Code","type":"string"},"is_eu":{"title":"Is Eu","type":"boolean"}}},"TimeZone":{"title":"TimeZone","type":"object","properties":{"id":{"title":"Id","type":"string"},"current_time":{"title":"Current Time","type":"string","format":"date-time"},"gmt_offset":{"title":"Gmt Offset","type":"integer"},"code":{"title":"Code","type":"string"},"is_daylight_saving":{"title":"Is Daylight Saving","type":"boolean"}}},"Currency":{"title":"Currency","type":"object","properties":{"code":{"title":"Code","type":"string"},"name":{"title":"Name","type":"string"},"plural":{"title":"Plural","type":"string"},"symbol":{"title":"Symbol","type":"string"},"symbol_native":{"title":"Symbol Native","type":"string"}}},"Connection":{"title":"Connection","type":"object","properties":{"asn":{"title":"Asn","type":"integer"},"isp":{"title":"Isp","type":"string"},"sld":{"title":"Sld","type":"string"},"tld":{"title":"Tld","type":"string"},"carrier":{"title":"Carrier","type":"string"},"home":{"title":"Home","type":"boolean"},"organization_type":{"title":"Organization Type","type":"string"},"isic_code":{"title":"Isic Code","type":"string"},"naics_code":{"title":"Naics Code","type":"string"}}},"Security":{"title":"Security","type":"object","properties":{"is_proxy":{"title":"Is Proxy","type":"boolean"},"proxy_type":{"title":"Proxy Type","type":"string"},"is_crawler":{"title":"Is Crawler","type":"boolean"},"crawler_name":{"title":"Crawler Name","type":"string"},"crawler_type":{"title":"Crawler Type","type":"string"},"is_tor":{"title":"Is Tor","type":"boolean"},"threat_level":{"title":"Threat Level","type":"string"},"threat_types":{"title":"Threat Types","type":"array","items":{"type":"string"}},"proxy_last_detected":{"title":"Proxy Last Detected","type":"string"},"proxy_level":{"title":"Proxy Level","type":"string"},"vpn_service":{"title":"Vpn Service","type":"string"},"anonymizer_status":{"title":"Anonymizer Status","type":"string"},"hosting_facility":{"title":"Hosting Facility","type":"boolean"}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"account_on_hold":{"summary":"account_on_hold","value":{"success":false,"error":{"code":107,"type":"account_on_hold","info":"Your account currently has open invoices and API has been automatically disabled. Please settle your open balance or downgrade to the Free Plan to restore API access. [Support: support@apilayer.com]"}}},"invalid_access_key":{"summary":"invalid_access_key","value":{"success":false,"error":{"code":101,"type":"invalid_access_key","info":"You have not supplied a valid API Access Key. [Technical Support: support@apilayer.com]"}}},"missing_access_key":{"summary":"missing_access_key","value":{"success":false,"error":{"code":101,"type":"missing_access_key","info":"You have not supplied an API Access Key. [Required format: access_key=YOUR_ACCESS_KEY]"}}},"inactive_user":{"summary":"inactive_user","value":{"success":false,"error":{"code":102,"type":"inactive_user","info":"Permission denied - User not active."}}}}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"https_access_restricted":{"summary":"https_access_restricted","value":{"success":false,"error":{"code":105,"type":"https_access_restricted","info":"Access Restricted - Your current Subscription Plan does not support HTTPS Encryption."}}},"function_access_restricted":{"summary":"function_access_restricted","value":{"success":false,"error":{"code":105,"type":"function_access_restricted","info":"Access Restricted - Your current Subscription Plan does not support this API Function."}}},"api_access_blocked":{"summary":"api_access_blocked","value":{"success":false,"error":{"code":104,"type":"api_access_blocked","info":"Your API access has been temporarily disabled. Please upgrade your Subscription Plan or contact support."}}}}}}},"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"invalid_api_function":{"summary":"invalid_api_function","value":{"success":false,"error":{"code":103,"type":"invalid_api_function","info":"This API Function does not exist."}}},"404_not_found":{"summary":"404_not_found","value":{"success":false,"error":{"code":404,"type":"404_not_found","info":"404 - The requested resource could not be found. Please try again or contact support."}}}}}}},"RateLimitReached":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"usage_limit_reached":{"summary":"usage_limit_reached","value":{"success":false,"error":{"code":104,"type":"usage_limit_reached","info":"Your monthly usage limit has been reached. Please upgrade your Subscription Plan."}}},"daily_usage_limit_reached":{"summary":"daily_usage_limit_reached","value":{"success":false,"error":{"code":104,"type":"daily_usage_limit_reached","info":"Your daily usage limit has been reached. Please try again tomorrow or upgrade your subscription plan."}}},"fair_use_limit_reached":{"summary":"fair_use_limit_reached","value":{"success":false,"error":{"code":104,"type":"fair_use_limit_reached","info":"Your fair use limit has been reached. [Please contact support: support@apilayer.com]"}}},"rate_limit_reached":{"summary":"rate_limit_reached","value":{"success":false,"error":{"code":106,"type":"rate_limit_reached","info":"You have exceeded the maximum rate limitation allowed on your subscription plan. Please refer to the \"Rate Limits\" section of the API Documentation for details. "}}}}}}},"InternalError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"internal_error":{"summary":"internal_error","value":{"success":false,"error":{"code":0,"type":"internal_error","info":"An error has occured. [Technical Support: support@apilayer.com]"}}}}}}},"Maintenance":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"maintenance_mode":{"summary":"maintenance_mode","value":{"success":false,"error":{"code":503,"type":"maintenance_mode","info":""}}}}}}}}}}