Announcing The IP Context V2 Schema

UPDATE 2022-02-09: Checkout our new dev portal and corresponding context api documentation.

Our Next Gen IP Context

Spur’s IP Context API was originally released in early 2020 with 10 proxy and 50 VPN services that we actively tracked and attributed. Today, we track over 40 different proxy providers and 600 VPN services. As we grew our service attribution, we felt a few pain points:

  1. Adding new metadata surrounding VPN services was nearly impossible with our current schema
  2. Customers want to make categorized judgements about connection risks without building complex logic
  3. Customers of the API had a difficult transition to our bulk data due to the schemas being different despite the data itself being the same
  4. Confusion over the difference between Maxmind’s GeoLite2 data and Spur’s GeoPrecision locations
  5. Residential proxies were co-located in the schema next to datacenter proxies which led to conflating the two despite the difference in risks they present

Version 2.0

We are excited to announce our version 2 schema. All customers have access to our new v2 context data. To make the switch, simply change v1 to v2 in your API requests for both the feed service and the Context API.

➜  ~ curl -s -H "token: $API_TOKEN" "https://api.spur.us/v2/context/185.65.135.235" | jq
{
"as": {
"number": 39351,
"organization": "31173 Services AB"
},
"client": {
"behaviors": [
"TOR_PROXY_USER",
"FILE_SHARING"
],
"concentration": {
"city": "Rasht",
"country": "IR",
"density": 1,
"geohash": "tnek0",
"skew": 3325,
"state": "Gīlān"
},
"count": 1,
"countries": 1
},
"infrastructure": "DATACENTER",
"ip": "185.65.135.235",
"location": {
"city": "Stockholm",
"country": "SE",
"state": "Stockholm County"
},
"organization": "31173 Services AB infrastructure in Stockholm, Sweden.",
"risks": [
"VPN_TUNNEL",
"GEO_MISMATCH"
],
"tunnels": [
{
"anonymous": true,
"entries": [
"185.65.135.70"
],
"operator": "MULLVAD_VPN",
"type": "VPN"
}
]
}

To summarize the major changes:

  1. The bulk data feeds and API have an identical schema
  2. The schema introduces more logical structures which will make feature additions simpler to integrate for customers
  3. We have clustered many of the old device metadata into a client object that encapsulates this information more clearly
  4. Residential/Call-back proxies are now split off from other proxy services and included in the client object
  5. All traditional proxy services are now included with the VPNs in a new tunnels object
  6. We now label risks to be wary of when interacting with these IP addresses at a high-level

Client Metadata

{
  "client": {
    "behaviors": [
      "TOR_PROXY_USER",
      "FILE_SHARING"
    ],
    "concentration": {
      "city": "Rasht",
      "country": "IR",
      "density": 1,
      "geohash": "tnek0",
      "skew": 3325,
      "state": "Gīlān"
    },
    "proxies": [
      "911_PROXY",
      "LUMINATI_PROXY"
    ],
    "count": 1,
    "countries": 1
  },
  ...
}

Tunnels

One of the biggest improvements is the data surrounding VPN/proxies.

{
  "tunnels": [
    {
      "anonymous": true,
      "entries": [
        "185.65.135.70"
      ],
      "operator": "MULLVAD_VPN",
      "type": "VPN"
    }
  ],
  ...
}
{
  "services": [
    "WIREGUARD"
  ],
  "tunnels": [
    {
      "anonymous": true,
      "exits": [
        "185.65.135.235",
        "185.65.135.240",
        "185.65.135.220"
      ],
      "operator": "MULLVAD_VPN",
      "type": "VPN"
    }
  ],
  ...
}

Full Documentation

The latest documentation can be downloaded here.

← Return to Blog

Context-API (2) Malware (3) Misc (2) Monocle (5) News (1) Residential Proxies (10)