NAV
shell python

Introduction

Welcome to the Focsec API Documentation.

These documents should help you to develop your integration. To use the API you will need an active API key, register here if you do not have an account yet.

Overview

Our API follows RESTful design principles and uses standard HTTP response codes, authentication, and verbs. All responses, including errors, return JSON.

The API is only accessible via HTTPS, the base URL is https://api.focsec.com/, and the current version is v1 which results in the following base URL for all requests: https://api.focsec.com/v1/.

Authentication

Authentication

# via Authorization header (recommended)
curl -X GET "https://api.focsec.com/v1/ip/82.40.11.200" \
  -H "Authorization: your-api-key-here"

# or via URL parameter
curl -X GET "https://api.focsec.com/v1/ip/82.40.11.200?api_key=your-api-key-here" 

import requests

# via Authorization header (recommended)
headers = {'Authorization': 'your-api-key-here'}
requests.get('https://api.focsec.com/v1/ip/82.40.11.200', headers=headers)

# or via URL parameter
params = {'api_key': 'your-api-key-here'}
requests.get('https://api.focsec.com/v1/ip/82.40.11.200', params=params)

API requests must be authenticated by including your API key. This key is secret, so be careful not to share it publicly and don't store it in the client side of your app.

The API key can either be included in the HTTP Authorization header (recommended) or be provided as a URL parameter.

Authentication via HTTP Header

Authorization: your-api-key-here

Authentication via URL query parameter

https://api.focsec.com/v1/ip/82.40.11.200?api_key=your-api-key-here

API

IP

curl -X GET "https://api.focsec.com/v1/ip/82.40.11.200" \
  -H "Authorization: your-api-key-here"

import requests

headers = {'Authorization': 'your-api-key-here'}
rsp = requests.get('https://api.focsec.com/v1/ip/82.40.11.200', headers=headers)

Response

{
  "ip": "82.40.11.200",
  "is_vpn": false,
  "is_proxy": true,
  "is_bot": false,
  "is_tor": false,
  "is_datacenter": true,
  "city": "Berlin",
  "country": "Germany",
  "iso_code": "de",
  "is_in_european_union": true,
  "flag": "🇩🇪",
  "autonomous_system_number": 6830,
  "autonomous_system_organization": "N1 Network Solutions"
}

Check a given IP

Request

Method GET

URL https://api.focsec.com/v1/ip/<ip-to-check-here>

Example URL: https://api.focsec.com/v1/ip/82.40.11.200

Response object

Field Type Description
ip string The given IP
is_vpn bool Indicates if IP is associated with VPN services
is_proxy bool Indicates if IP is associated with Proxy services
is_bot bool Indicates if IP is a malicious bot
is_tor bool Indicates if IP is part of the TOR network
is_datacenter bool Indicates if IP belongs to a datacenter, cloud or hosting company
city string Approximate city
country string Country
iso_code string ISO 3166 2-letter country code
is_in_european_union bool If the country is a EU member state
flag string Emoji flag of the country
autonomous_system_number int Number of the AS that manages the IP
autonomous_system_organization string Name of the AS organization that manages the IP

Database

curl -X GET "https://api.focsec.com/v1/database/vpn.txt.gz" \
  -H "Authorization: your-api-key-here"

import requests

headers = {'Authorization': 'your-api-key-here'}
rsp = requests.get('https://api.focsec.com/v1/database/vpn.txt.gz', headers=headers)

Response

[Binary data]

Download a database

⚠️ This feature is only available for subscribers with an Enterprise plan

Request

Method GET

URL https://api.focsec.com/v1/database/<database_name>.<format>.gz

Example URL: https://api.focsec.com/v1/database/vpn.txt.gz

Valid database_name are: all, vpn, proxy, bot, tor

Valid format are: txt, csv, jsonl

Response object

The response is the gzipped database in the requested format.

Response codes

Code Type Description
200 OK Request successful
400 Bad Request Requested database was not found

Errors

Client-side errors

Code Type Meaning
400 Bad Request Something is wrong with the request, check response body for details
401 Unauthorized API key not provided or not valid
402 Payment Required Subscription or trial period expired, please renew your subscription
404 Not Found The URL was not found
405 Method Not Allowed The request method (GET, POST, PUT, DELETE) is not allowed for this URL
429 Too Many Requests Daily request limit exceeded

Server-side errors

Code Type Meaning
500 Internal Server Error Something went wrong on our side while processing the request
502 Bad Gateway API temporarily not available
503 Service Unavailable API temporarily not available

Request limits

Your accounts daily request limits are included in the HTTP response headers. Limits are reset daily at midnight (UTC time).

Header Meaning
X-RequestLimit-RequestsMadeToday Total number of requests made today
X-RequestLimit-RequestsRemainingToday Number of requests remaining today

Miscellaneous

shell python