Locations API

Every country, region, city, ISP and carrier you can target, with the value to put in the proxy login.

Targeting values come from these lists, never from guesses: a value outside them makes the gateway answer 407, and it never falls back to the whole country. Each item has a name as the network names it ("new york") and a slug, the form the proxy login uses (newyork).

Region and city lists exist for every country. ISP lists (residential) and carrier lists (mobile) exist for the United States, the United Kingdom and Germany so far. The lists follow our upstream network and are cached for a day, so fetch them when you build a picker rather than on every request.

List countries

GET/api/v1/locations/countries

Countries with exits on the product right now. code is what country and the -cc- key take.

Query parameters

Name	Type	Description
`product`required	residential \| mobile	Which pool: `residential` or `mobile`.

Request

curl "https://aeonproxy.com/api/v1/locations/countries?product=residential" \
  -H "Authorization: Bearer $AEONPROXY_API_KEY"

import os
import requests

r = requests.get(
    "https://aeonproxy.com/api/v1/locations/countries?product=residential",
    headers={"Authorization": f"Bearer {os.environ['AEONPROXY_API_KEY']}"},
    timeout=30,
)
data = r.json()
if not r.ok:
    raise SystemExit(data["error"]["message"])
print(data)

// Node.js 18+, as an ES module (.mjs)
const res = await fetch("https://aeonproxy.com/api/v1/locations/countries?product=residential", {
  headers: {
    Authorization: `Bearer ${process.env.AEONPROXY_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error.message);
console.log(data);

<?php
$ch = curl_init('https://aeonproxy.com/api/v1/locations/countries?product=residential');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AEONPROXY_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$data = json_decode($body, true);
if ($status >= 400) {
    fwrite(STDERR, $data['error']['message'] . PHP_EOL);
    exit(1);
}
print_r($data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://aeonproxy.com/api/v1/locations/countries?product=residential", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AEONPROXY_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status)
	fmt.Println(string(out))
}

Response 200

{
  "product": "residential",
  "count": 3,
  "results": [
    {
      "code": "us",
      "name": "United States"
    },
    {
      "code": "gb",
      "name": "United Kingdom"
    },
    {
      "code": "de",
      "name": "Germany"
    }
  ]
}

Errors

Status	Code	When
400	`invalid_parameter`	`product` is missing or not `residential` / `mobile`

List regions

GET/api/v1/locations/regions

States, provinces or nations of one country. The slug goes into the -st- key: ap_…-cc-us-st-newyork.

Query parameters

Name	Type	Description
`product`required	residential \| mobile	Which pool: `residential` or `mobile`.
`country`required	string	Two-letter country code from countries, e.g. `us`, `gb`, `de`.

Request

curl "https://aeonproxy.com/api/v1/locations/regions?product=residential&country=us" \
  -H "Authorization: Bearer $AEONPROXY_API_KEY"

import os
import requests

r = requests.get(
    "https://aeonproxy.com/api/v1/locations/regions?product=residential&country=us",
    headers={"Authorization": f"Bearer {os.environ['AEONPROXY_API_KEY']}"},
    timeout=30,
)
data = r.json()
if not r.ok:
    raise SystemExit(data["error"]["message"])
print(data)

// Node.js 18+, as an ES module (.mjs)
const res = await fetch("https://aeonproxy.com/api/v1/locations/regions?product=residential&country=us", {
  headers: {
    Authorization: `Bearer ${process.env.AEONPROXY_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error.message);
console.log(data);

<?php
$ch = curl_init('https://aeonproxy.com/api/v1/locations/regions?product=residential&country=us');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AEONPROXY_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$data = json_decode($body, true);
if ($status >= 400) {
    fwrite(STDERR, $data['error']['message'] . PHP_EOL);
    exit(1);
}
print_r($data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://aeonproxy.com/api/v1/locations/regions?product=residential&country=us", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AEONPROXY_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status)
	fmt.Println(string(out))
}

Response 200

{
  "product": "residential",
  "country": "us",
  "count": 3,
  "results": [
    {
      "name": "california",
      "slug": "california"
    },
    {
      "name": "new york",
      "slug": "newyork"
    },
    {
      "name": "texas",
      "slug": "texas"
    }
  ]
}

Errors

Status	Code	When
400	`invalid_parameter`	`product` is missing or not `residential` / `mobile`
400	`invalid_parameter`	the country is not in the product's list

List cities

GET/api/v1/locations/cities

Cities of one country, filtered by search and paged with limit and offset (the United States alone has thousands). count is the number of matches before paging. The slug goes into the -city- key.

Query parameters

Name	Type	Description
`product`required	residential \| mobile	Which pool: `residential` or `mobile`.
`country`required	string	Two-letter country code from countries, e.g. `us`, `gb`, `de`.
`search`	string	Only cities whose name contains this text (case-insensitive).
`limit`	integer	Page size. 1–1000. Default `100`.
`offset`	integer	How many matches to skip. From 0. Default `0`.

Request

curl "https://aeonproxy.com/api/v1/locations/cities?product=residential&country=us&search=san&limit=3" \
  -H "Authorization: Bearer $AEONPROXY_API_KEY"

import os
import requests

r = requests.get(
    "https://aeonproxy.com/api/v1/locations/cities?product=residential&country=us&search=san&limit=3",
    headers={"Authorization": f"Bearer {os.environ['AEONPROXY_API_KEY']}"},
    timeout=30,
)
data = r.json()
if not r.ok:
    raise SystemExit(data["error"]["message"])
print(data)

// Node.js 18+, as an ES module (.mjs)
const res = await fetch("https://aeonproxy.com/api/v1/locations/cities?product=residential&country=us&search=san&limit=3", {
  headers: {
    Authorization: `Bearer ${process.env.AEONPROXY_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error.message);
console.log(data);

<?php
$ch = curl_init('https://aeonproxy.com/api/v1/locations/cities?product=residential&country=us&search=san&limit=3');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AEONPROXY_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$data = json_decode($body, true);
if ($status >= 400) {
    fwrite(STDERR, $data['error']['message'] . PHP_EOL);
    exit(1);
}
print_r($data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://aeonproxy.com/api/v1/locations/cities?product=residential&country=us&search=san&limit=3", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AEONPROXY_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status)
	fmt.Println(string(out))
}

Response 200

{
  "product": "residential",
  "country": "us",
  "count": 41,
  "limit": 3,
  "offset": 0,
  "results": [
    {
      "name": "san antonio",
      "slug": "sanantonio"
    },
    {
      "name": "san diego",
      "slug": "sandiego"
    },
    {
      "name": "san francisco",
      "slug": "sanfrancisco"
    }
  ]
}

Errors

Status	Code	When
400	`invalid_parameter`	`product` is missing or not `residential` / `mobile`
400	`invalid_parameter`	the country is not in the product's list

List ISPs and carriers

GET/api/v1/locations/isps

Home ISPs (residential) or mobile carriers (mobile) of one country. Residential logins take the slug in -isp-, mobile ones in -car-. An empty list means the country has no network targeting yet.

Query parameters

Name	Type	Description
`product`required	residential \| mobile	Which pool: `residential` or `mobile`.
`country`required	string	Two-letter country code from countries, e.g. `us`, `gb`, `de`.

Request

curl "https://aeonproxy.com/api/v1/locations/isps?product=residential&country=us" \
  -H "Authorization: Bearer $AEONPROXY_API_KEY"

import os
import requests

r = requests.get(
    "https://aeonproxy.com/api/v1/locations/isps?product=residential&country=us",
    headers={"Authorization": f"Bearer {os.environ['AEONPROXY_API_KEY']}"},
    timeout=30,
)
data = r.json()
if not r.ok:
    raise SystemExit(data["error"]["message"])
print(data)

// Node.js 18+, as an ES module (.mjs)
const res = await fetch("https://aeonproxy.com/api/v1/locations/isps?product=residential&country=us", {
  headers: {
    Authorization: `Bearer ${process.env.AEONPROXY_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error.message);
console.log(data);

<?php
$ch = curl_init('https://aeonproxy.com/api/v1/locations/isps?product=residential&country=us');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AEONPROXY_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$data = json_decode($body, true);
if ($status >= 400) {
    fwrite(STDERR, $data['error']['message'] . PHP_EOL);
    exit(1);
}
print_r($data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://aeonproxy.com/api/v1/locations/isps?product=residential&country=us", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AEONPROXY_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status)
	fmt.Println(string(out))
}

Response 200

{
  "product": "residential",
  "country": "us",
  "kind": "isp",
  "count": 2,
  "results": [
    {
      "name": "comcast cable",
      "slug": "comcastcable"
    },
    {
      "name": "charter communications",
      "slug": "chartercommunications"
    }
  ]
}

Errors

Status	Code	When
400	`invalid_parameter`	`product` is missing or not `residential` / `mobile`
400	`invalid_parameter`	the country is not in the product's list

Your API key is already in the dashboard.

Create an account API overview

Locations API

List countries

Query parameters

Request

Response 200

Errors

List regions

Query parameters

Request

Response 200

Errors

List cities

Query parameters

Request

Response 200

Errors

List ISPs and carriers

Query parameters

Request

Response 200

Errors

See also

Your API key is already in the dashboard.