# Quickstart

> Look up an IPv4 or IPv6 address over HTTP, with an official server SDK, or from a local MMDB file in under five minutes.

IPScope delivers IP intelligence in two interchangeable forms: a low-latency [REST API](https://ipscope.io/docs/api-reference) at `https://api.ipscope.io` and [downloadable databases](https://ipscope.io/docs/databases) (`.mmdb`, `.csv.gz`, `.parquet`) that run on your own servers with zero network hops. Both return the same 6 intelligence blocks.

### Step 1: Try your first lookup (no key needed)

Look up the address you are connecting from right now via `/v1/ip/me`:

```bash curl
curl -sS https://api.ipscope.io/v1/ip/me
```

```json 200 OK
{
  "ip": "198.51.100.7",
  "ip_version": 4,
  "matched_network": "198.51.100.0/24",
  "geo": {
    "country_code": "US",
    "declared_country_code": "US",
    "physical_country_code": "US",
    "is_virtual_location": false,
    "location_type": "physical",
    "confidence": 0.94,
    "subdivision": "Virginia",
    "city": "Ashburn",
    "postal_code": "20147",
    "latitude": 39.0438,
    "longitude": -77.4874,
    "accuracy_radius_km": 10,
    "timezone": "America/New_York"
  },
  "network": {
    "asn": 64501,
    "organization": "Example Cloud LLC"
  },
  "connection": {
    "connection_type": "hosting",
    "is_hosting": true,
    "is_residential": false,
    "is_mobile": false,
    "is_business": false
  },
  "security": {
    "is_vpn": true,
    "is_hosting": true,
    "is_tor_exit": false,
    "is_proxy": false,
    "anonymizer_type": "vpn",
    "confidence": 0.96,
    "reason_codes": [
      "vpn_handshake_confirmed",
      "datacenter_asn_range"
    ]
  }
}
```

Create a free account in the [dashboard](https://dashboard.ipscope.io/auth/login) to generate a server API key (`ips_live_...`) with 30,000 free lookups every month.

### Step 2: Look up any IPv4 or IPv6 address

Pass your API key in `Authorization: Bearer $IPSCOPE_KEY` (or `X-API-Key`) to query `/v1/ip/{ip}` from `curl` or any of our [8 official server SDKs](https://ipscope.io/docs/sdks):

```bash curl
curl -sS "https://api.ipscope.io/v1/ip/198.51.100.7" \
  -H "Authorization: Bearer $IPSCOPE_KEY"
```

```python Python
import asyncio, os
from ipscope import AsyncIpScopeClient

async def main() -> None:
    async with AsyncIpScopeClient(api_key=os.environ["IPSCOPE_KEY"]) as client:
        record = await client.lookup_ip("198.51.100.7")
        print(record["ip"], record["geo"]["country_code"], record["security"]["is_vpn"])

asyncio.run(main())
```

```ts Node.js
import { IpScopeClient } from '@ipscope/sdk-node';

const client = new IpScopeClient({ apiKey: process.env.IPSCOPE_KEY });
const record = await client.lookupIp('198.51.100.7');
console.log(record.ip, record.geo?.country_code, record.security?.is_vpn);
```

```go Go
client := ipscope.NewClient(ipscope.Config{APIKey: os.Getenv("IPSCOPE_KEY")})
defer client.Close()

record, err := client.LookupIP(ctx, "198.51.100.7")
if err != nil {
	return err
}
fmt.Println(record.IP, record.Security.IsVPN)
```

```rust Rust
use ipscope::{AsyncIpScopeClient, ClientConfig};

let client = AsyncIpScopeClient::new(ClientConfig::new(std::env::var("IPSCOPE_KEY")?))?;
let record = client.lookup_ip("198.51.100.7").await?;
println!("{} VPN={}", record.ip, record.security.is_vpn);
```

```java Java
import io.ipscope.sdk.IpScopeClient;
import io.ipscope.sdk.IpScopeConfig;

IpScopeConfig config = IpScopeConfig.builder().apiKey(System.getenv("IPSCOPE_KEY")).build();
try (IpScopeClient client = new IpScopeClient(config)) {
    var record = client.lookupIp("198.51.100.7");
    System.out.println(record.ip() + " " + record.geo().countryCode());
}
```

```csharp .NET
using IpScope.Sdk;

using var client = new IpScopeClient(new IpScopeClientOptions {
    ApiKey = Environment.GetEnvironmentVariable("IPSCOPE_KEY")
});
var record = await client.LookupIpAsync("198.51.100.7");
Console.WriteLine($"{record.Ip} {record.Geo?.CountryCode} VPN={record.Security?.IsVpn}");
```

```ruby Ruby
require "ipscope"

client = IpScope::Client.new(api_key: ENV.fetch("IPSCOPE_KEY"))
record = client.lookup_ip("198.51.100.7")
puts "#{record.ip} #{record.geo.country_code} VPN=#{record.security.is_vpn}"
```

```php PHP
<?php
use IpScope\Sdk\IpScopeClient;

$client = new IpScopeClient(apiKey: getenv('IPSCOPE_KEY') ?: '');
$record = $client->lookupIp('198.51.100.7');
echo $record->ip . " " . $record->geo->countryCode . PHP_EOL;
```

```json 200 OK
{
  "ip": "198.51.100.7",
  "ip_version": 4,
  "matched_network": "198.51.100.0/24",
  "geo": {
    "country_code": "US",
    "declared_country_code": "US",
    "physical_country_code": "US",
    "is_virtual_location": false,
    "location_type": "physical",
    "confidence": 0.94,
    "subdivision": "Virginia",
    "city": "Ashburn",
    "postal_code": "20147",
    "latitude": 39.0438,
    "longitude": -77.4874,
    "accuracy_radius_km": 10,
    "timezone": "America/New_York"
  },
  "network": {
    "asn": 64501,
    "organization": "Example Cloud LLC"
  },
  "connection": {
    "connection_type": "hosting",
    "is_hosting": true,
    "is_residential": false,
    "is_mobile": false,
    "is_business": false
  },
  "security": {
    "is_vpn": true,
    "is_hosting": true,
    "is_tor_exit": false,
    "is_proxy": false,
    "anonymizer_type": "vpn",
    "confidence": 0.96,
    "reason_codes": [
      "vpn_handshake_confirmed",
      "datacenter_asn_range"
    ]
  },
  "security_extensions": {
    "abuse_velocity_score": 18,
    "is_known_scanner": false,
    "observation_recency_hours": 12,
    "anonymizer_reason": "vpn_handshake_confirmed",
    "threat_level": "medium",
    "abuse_velocity": "low",
    "confidence": 0.96
  },
  "dataset_version": "2026-10-27T00:00:00Z.crawl-1793088000000",
  "updated_at": "2026-10-27T00:00:00Z"
}
```

### Step 3: Request only the intelligence blocks you need

Every response groups attributes into 6 modular families (`geo_country`, `geo_city`, `network`, `connection`, `anonymity`, `security_extensions`). Pass `?field_families=` to restrict the payload to the blocks your handler inspects:

```bash curl
curl -sS "https://api.ipscope.io/v1/ip/198.51.100.7?field_families=geo_country,anonymity" \
  -H "Authorization: Bearer $IPSCOPE_KEY"
```

```json 200 OK
{
  "ip": "198.51.100.7",
  "ip_version": 4,
  "matched_network": "198.51.100.0/24",
  "geo": {
    "country_code": "US",
    "declared_country_code": "US",
    "physical_country_code": "US",
    "is_virtual_location": false,
    "location_type": "physical",
    "confidence": 0.94
  },
  "security": {
    "is_vpn": true,
    "is_hosting": true,
    "is_tor_exit": false,
    "is_proxy": false,
    "anonymizer_type": "vpn",
    "confidence": 0.96,
    "reason_codes": [
      "vpn_handshake_confirmed",
      "datacenter_asn_range"
    ]
  }
}
```

### Step 4: Or run lookups locally from an MMDB file

If you prefer zero external network calls on the request path, download any [database edition](https://ipscope.io/docs/databases) (starting with the free [IPScope Lite](https://ipscope.io/docs/databases) edition) and open it with your existing MaxMind DB reader:

```python Python
import maxminddb

with maxminddb.open_database("/var/lib/ipscope/ipscope-complete.mmdb") as reader:
    record = reader.get("198.51.100.7")
    print(record["geo"]["country_code"], record["security"]["is_vpn"])
```

```js Node.js
import maxmind from 'maxmind';

const reader = await maxmind.open('/var/lib/ipscope/ipscope-complete.mmdb');
console.log(reader.get('198.51.100.7'));
```

```go Go
db, _ := maxminddb.Open("/var/lib/ipscope/ipscope-complete.mmdb")
defer db.Close()

var record map[string]any
_ = db.Lookup(net.ParseIP("198.51.100.7"), &record)
```

## Next steps

- [Official Server SDKs](https://ipscope.io/docs/sdks): Install the Python, Node.js, Go, Rust, Java, .NET, Ruby or PHP SDK with built-in LRU caching.
- [Authentication](https://ipscope.io/docs/getting-started/authentication): How API keys work, header formats, key rotation, and environment variables.
- [Field reference](https://ipscope.io/docs/getting-started/data/fields): Every attribute in `geo`, `network`, `connection`, `security` and `security_extensions`.
- [Database editions](https://ipscope.io/docs/databases): Compare Lite, Country, ASN, City, Privacy and Enterprise Mega `.mmdb`, `.csv.gz` and `.parquet` files.