App

Exports API

The Exports API is the Swiss Army knife of pre-processing and filtering Spur data feeds for integration into third-party tools or components. Both the Anonymous data feed and the Anonymous +Residential data feed in normal and IPv6 versions are supported.

Note

⚠️ The Exports API is designed to generate subsets of Spur feeds for integration with other systems. For example, a list of specific service tags or locations. The Exports API is not designed for high-frequency polling or full feed downloads. In those cases, please refer to our feed types page for full downloads. The Exports API may apply rate limits to prevent abuse.

Access and Setup

All feed authentication is performed with a Token header.

BASE URL
https://exports.spur.us

Response Codes

CodeDescription
200The request succeeded.
403Access is denied, your token is most likely invalid.
429Too many requests. Try again later.
500An error occurred.

Endpoints

Customize the Anonymous feed

Export filtered data from the Anonymous feed in CSV, JSON, or MMDB format.

output (string)
The format of the output file. One of csv, json, or mmdb.
Defaults to csv.

includeCSVHeader (boolean)
Whether to include a header row in CSV output.
Only applies if output is csv.
Defaults to false.

fields (string)
Comma-separated list of fields to include in the export.
Valid fields: ip, tag, infrastructure, services, clientCount, locationCity, locationState, locationCountry, network.

Note

⚠️ If network is included, IPs are collapsed into CIDR blocks. This disables the diff parameter and excludes ip and services.

limit (integer)
Maximum number of records to return.
Defaults to 2,000,000.

tags (string)
Comma-separated list of service tags to include.
Defaults to all tags.

ccs (string)
Comma-separated list of ISO country codes to include.

attributed (boolean)
Whether to include only attributed/named VPN exits.

diff (boolean)
Whether to return only changes since the previous day.
Incompatible with the network field.

diffDate (string) (date)
Specify a date (YYYY-MM-DD) to generate a diff compared to the previous day.


GET /v1/feeds/anonymous
curl --get "https://exports.spur.us/v1/feeds/anonymous" \
  --data-urlencode "output=csv" \
  --data-urlencode "includeCSVHeader=true" \
  --data-urlencode "fields=network,tag,locationCountry" \
  --data-urlencode "tags=EXPRESS_VPN" \
  --data-urlencode "ccs=US,DE,FR" \
  --data-urlencode "attributed=true" \
  -H "Token: $TOKEN" \
  -o output.csv
output.csv
network,tag,locationCountry
216.73.163.0/24,EXPRESS_VPN,US
216.24.210.64/26,EXPRESS_VPN,US
216.24.210.128/26,EXPRESS_VPN,US
185.223.152.128/26,EXPRESS_VPN,US
98.159.37.128/26,EXPRESS_VPN,US
185.223.152.64/26,EXPRESS_VPN,US
98.159.37.64/26,EXPRESS_VPN,US
92.119.36.64/26,EXPRESS_VPN,US
193.56.116.64/26,EXPRESS_VPN,US
...

Customize the Anonymous +Residential feed

Export filtered data from the Anonymous feed in CSV, JSON, or MMDB format. This feed includes residential proxy and other callback proxy services through the callbackProxies filter parameter.

output (string)
The format of the output file. One of csv, json, or mmdb.
Defaults to csv.

includeCSVHeader (boolean)
Whether to include a header row in CSV output.
Only applies if output is csv.
Defaults to false.

fields (string)
Comma-separated list of fields to include in the export.
Valid fields: ip, tag, infrastructure, services, clientCount, locationCity, locationState, locationCountry, network.

Note

⚠️ If network is included, IPs are collapsed into CIDR blocks. This disables the diff parameter and excludes ip and services.

callbackProxies (string)
Comma-separated list of service tags to filter for in the client.proxies field.
Only supported in anonymous-residential feed types.

limit (integer)
Maximum number of records to return.
Defaults to 2,000,000.

tags (string)
Comma-separated list of service tags to include.
Defaults to all tags.

ccs (string)
Comma-separated list of ISO country codes to include.

attributed (boolean)
Whether to include only attributed/named VPN exits.

diff (boolean)
Whether to return only changes since the previous day.
Incompatible with the network field.

diffDate (string) (date)
Specify a date (YYYY-MM-DD) to generate a diff compared to the previous day.


GET /v1/feeds/anonymous-residential
curl --get "https://exports.spur.us/v1/feeds/anonymous-residential" \
  --data-urlencode "output=csv" \
  --data-urlencode "includeCSVHeader=true" \
  --data-urlencode "fields=network" \
  --data-urlencode "callbackProxies=YILU_PROXY" \
  --data-urlencode "ccs=US" \
  -H "Token: $TOKEN" \
  -o output.csv
output.csv
network
152.44.64.16/30
68.193.238.172/30
208.104.75.64/31
206.125.156.128/29
67.20.0.160/27
73.145.242.136/30
69.24.120.152/31
70.126.7.68/30
73.29.13.180/30
73.145.241.128/27
...

The Exports IP Context Object

The Exports API uses a reduced and flattened version of the IP Context Object. This is necessary to support additional data formats such as CSV and MMDB. All fields except for ip or network may be omitted when the value is null.

Attributes
ip | networkstring

The IP Address or network in CIDR notation for this record. This can be IPv4 or IPv6.

tagstring

The name of the anonymization service.

callbackProxystring

The name of a callbackProxy service on the IP.

infrastructurestring

The type of infrastructure.

servicesarray of strings

An array of listening services on that IP Address.

clientCountinteger

The daily average number of devices on this IP Address.

locationCitystring

The MaxMind GeoLite2 city location of the IP Address.

locationStatestring

The MaxMind GeoLite2 state location of the IP Address.

locationCountrystring

The MaxMind GeoLite2 country location of the IP Address.

diffstring

Only present if generating a diff file. This marks a record to be added or removed.

EXPORTS IP CONTEXT OBJECT (JSON)
{
  "clientCount": 54,
  "infrastructure": "DATACENTER",
  "ip": "45.67.96.41",
  "locationCity": "Sydney",
  "locationCountry": "AU",
  "locationState": "New South Wales",
  "services": null,
  "tag": "EXPRESS_VPN"
}
EXPORTS IP CONTEXT OBJECT (CSV)
ip,tag,infrastructure,services,clientCount,locationCity,locationState,locationCountry
45.67.96.41,EXPRESS_VPN,DATACENTER,[],54,Sydney,New South Wales,AU
45.67.96.67,EXPRESS_VPN,DATACENTER,[],52,Sydney,New South Wales,AU
45.67.96.23,EXPRESS_VPN,DATACENTER,[],52,Sydney,New South Wales,AU
45.67.96.199,EXPRESS_VPN,DATACENTER,[],48,Sydney,New South Wales,AU
45.67.96.163,EXPRESS_VPN,DATACENTER,[],47,Sydney,New South Wales,AU
45.67.96.79,EXPRESS_VPN,DATACENTER,[],47,Sydney,New South Wales,AU
45.67.96.109,EXPRESS_VPN,DATACENTER,[],46,Sydney,New South Wales,AU
45.67.96.17,EXPRESS_VPN,DATACENTER,[],46,Sydney,New South Wales,AU
45.67.96.175,EXPRESS_VPN,DATACENTER,[],44,Sydney,New South Wales,AU

Common recipes and use-cases

Download the Anonymous feed as CSV

Fetches the Anonymous feed with default fields in CSV format.


GET /v1/feeds/anonymous
curl --get "https://exports.spur.us/v1/feeds/anonymous" \
  --data-urlencode "output=csv" \
  -H "Token: $TOKEN" \
  -o anonymous.csv

Download the Anonymous feed as MMDB

Fetches the Anonymous feed in MaxMind DB format.

Note

⚠️ This may be a long-running request. For best results, filter the types of IPs you want to include.


GET /v1/feeds/anonymous
curl --get "https://exports.spur.us/v1/feeds/anonymous" \
  --data-urlencode "output=mmdb" \
  -H "Token: $TOKEN" \
  -o anonymous.mmdb

Fetch all IPs for a VPN provider

Uses the Anonymous feed to grab all of the active IPs for MULLVAD_VPN. You can replace this with any other commercial VPN provider.


GET /v1/feeds/anonymous
curl --get "https://exports.spur.us/v1/feeds/anonymous" \
  --data-urlencode "tags=MULLVAD_VPN" \
  --data-urlencode "fields=ip,tag" \
  --data-urlencode "output=csv" \
  --data-urlencode "includeCSVHeader=true" \
  -H "Token: $TOKEN" \
  -o output.csv

Fetch all anonymous exits in the USA as CIDR blocks

Uses the Anonymous feed to grab all of the active IPs with an IP Geo of US and collapse them into netblocks with tags.


GET /v1/feeds/anonymous
curl --get "https://exports.spur.us/v1/feeds/anonymous" \
  --data-urlencode "ccs=US" \
  --data-urlencode "fields=network,tag" \
  --data-urlencode "output=csv" \
  --data-urlencode "includeCSVHeader=true" \
  -H "Token: $TOKEN" \
  -o output.csv

Fetch all IPs for a residential proxy provider

Uses the Anonymous +Residential feed to grab all of the active IPs for IPIDEA_PROXY. You can replace this with any other residential proxy provider. Change output to json or mmdb for different file formats.


GET /v1/feeds/anonymous-residential
curl --get "https://exports.spur.us/v1/feeds/anonymous-residential" \
  --data-urlencode "callbackProxies=IPIDEA_PROXY" \
  --data-urlencode "fields=ip" \
  --data-urlencode "output=csv" \
  --data-urlencode "includeCSVHeader=true" \
  -H "Token: $TOKEN" \
  -o output.csv

FAQs

When should I use the Exports API?

The Exports API is designed to support environments or situations where pre-processing is not possible. For example, direct integration into a SIEM, IPS, or Firewall. If you require the full feed data, we recommend downloading the entire feed and performing your own mutation locally.