Locations — SpiderIQ

POST/api/v1/locations/import

Import locations

Import multiple locations into the database.

Use Cases:

Add postcodes for a specific city (e.g., Paris postcodes 75001-75020)
Add custom locations for a region
Bulk import city data

Example - Add Paris postcodes:

    {
      "country_code": "FR",
      "parent_city": "Paris",
      "location_type": "postcode",
      "locations": [
        {"search_string": "75001, France", "display_name": "Paris 1er", "latitude": 48.86, "longitude": 2.34},
        {"search_string": "75002, France", "display_name": "Paris 2ème", "latitude": 48.87, "longitude": 2.34}
      ]
    }

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/locations/import' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "country_code": "string",
  "country_name": "string",
  "location_type": "city",
  "parent_city": "string",
  "locations": [
    {
      "search_string": "string",
      "display_name": "string",
      "latitude": 0.0,
      "longitude": 0.0,
      "admin_region": "string",
      "population": 0
    }
  ]
}'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/locations/import",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"country_code": "string", "country_name": "string", "location_type": "city", "parent_city": "string", "locations": [{"search_string": "string", "display_name": "string", "latitude": 0.0, "longitude": 0.0, "admin_region": "string", "population": 0}]},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/locations/import", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"country_code": "string", "country_name": "string", "location_type": "city", "parent_city": "string", "locations": [{"search_string": "string", "display_name": "string", "latitude": 0.0, "longitude": 0.0, "admin_region": "string", "population": 0}]})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"country_code": "string", "country_name": "string", "location_type": "city", "parent_city": "string", "locations": [{"search_string": "string", "display_name": "string", "latitude": 0.0, "longitude": 0.0, "admin_region": "string", "population": 0}]}`)
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/locations/import", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`201`	Successful Response
`422`	Validation Error

GET/api/v1/locations

List locations

List locations with filtering and pagination.

Filter Options:

country_code: Filter by ISO 2-letter country code (e.g., FR, DE, US)
location_type: Filter by type (city or postcode)
parent_city: Filter postcodes by parent city
admin_region: Filter by state/province/region
min_population / max_population: Filter by population range
needs_postcodes: Filter big cities that need postcode breakdown
search: Search in display_name or search_string

Parameters

Name	In	Type	Required	Description
`country_code`	query	any	false	ISO 2-letter country code
`location_type`	query	any	false	Location type
`parent_city`	query	any	false	Parent city (for postcodes)
`admin_region`	query	any	false	State/Province/Region
`min_population`	query	any	false	Minimum population
`max_population`	query	any	false	Maximum population
`needs_postcodes`	query	any	false	Filter big cities needing postcodes
`search`	query	any	false	Search in display_name or search_string
`page`	query	integer	false	Page number
`page_size`	query	integer	false	Items per page

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/locations' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/locations",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/locations", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/locations", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/locations/countries

List available countries

Get list of all countries with location counts.

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/locations/countries' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/locations/countries",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/locations/countries", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/locations/countries", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response

GET/api/v1/locations/regions

List admin regions (states) for a country

List the admin regions (US states / provinces) of a country, each with its city/postcode split. For US ZIP campaigns the state is the selection unit — pick one region and run its postcodes (each ZIP is its own Maps search). 'All of US' is not selectable for a ZIP campaign (the volume guard 422s ~46K locations / >10K cap).

Parameters

Name	In	Type	Required	Description
`country_code`	query	string	true	ISO country code, e.g. US

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/locations/regions' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/locations/regions",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/locations/regions", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/locations/regions", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/locations/selectable-units

List selectable geo units (countries + US states)

Flat, alphabetically merged list of selectable geo units for a typeahead picker. Each unit is a whole country (kind='country') or a US state (kind='state'). With states_as_units=true (default) the US row is dropped and its 50 states appear as top-level units — so an agent targets 'Florida' the same way it targets 'Germany', and 'all of USA' cannot be picked for a ZIP campaign. Set states_as_units=false for plain countries (US included) when the country is the correct unit.

Parameters

Name	In	Type	Required	Description
`states_as_units`	query	boolean	false	When true (default), replace US with its 50 states as top-level units.

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/locations/selectable-units' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/locations/selectable-units",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/locations/selectable-units", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/locations/selectable-units", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/locations/stats

Get location statistics

Get overall location database statistics.

Returns:

Total locations, countries, cities, postcodes
Count of cities needing postcode breakdown
Top 20 countries by location count

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/locations/stats' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/locations/stats",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/locations/stats", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/locations/stats", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response

GET/api/v1/locations/{location_id}

Get location by ID

Get details of a specific location.

Parameters

Name	In	Type	Required	Description
`location_id`	path	integer	true

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/locations/{location_id}' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/locations/{location_id}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/locations/{location_id}", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/locations/{location_id}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error