GET
https://spideriq.di-atomic.com
/
api
/
v1
/
locations
List Locations
curl --request GET \
  --url https://spideriq.di-atomic.com/api/v1/locations \
  --header 'Authorization: Bearer <token>'
{
  "locations": [
    {
      "location_id": 123,
      "country_code": "<string>",
      "country_name": "<string>",
      "search_string": "<string>",
      "location_type": "<string>",
      "display_name": "<string>",
      "parent_city": "<string>",
      "admin_region": "<string>",
      "latitude": 123,
      "longitude": 123,
      "population": 123,
      "needs_postcodes": true,
      "created_at": "<string>"
    }
  ],
  "total": 123,
  "page": 123,
  "page_size": 123,
  "total_pages": 123
}

​
Overview

Query the global location database with various filters. The database contains 44,691 cities across 240 countries.
v2.14.0 Feature: The location database is used by the Campaign System to orchestrate multi-location scraping.

​
Query Parameters

​
country_code
string
ISO 2-letter country code (e.g., “FR”, “DE”, “US”)
​
location_type
string
Filter by type: city or postcode
​
parent_city
string
Filter postcodes by parent city
​
admin_region
string
Filter by state/province/region
​
min_population
integer
Minimum population filter
​
max_population
integer
Maximum population filter
​
needs_postcodes
boolean
Filter big cities needing postcode breakdown
​
search
string
Search in display_name or search_string
​
page
integer
default:"1"
Page number
​
page_size
integer
default:"50"
Items per page (1-500)

​
Response

​
locations
array
Array of location objects
​
total
integer
Total matching locations
​
page
integer
Current page
​
page_size
integer
Items per page
​
total_pages
integer
Total pages

​
Examples

​
List French Cities

curl "https://spideriq.di-atomic.com/api/v1/locations?country_code=FR&page_size=5" \
  -H "Authorization: Bearer <your_token>"
Response: 
{
  "locations": [
    {
      "location_id": 15001,
      "country_code": "FR",
      "country_name": "France",
      "search_string": "Paris, France",
      "location_type": "city",
      "display_name": "Paris",
      "parent_city": null,
      "admin_region": "Ile-de-France",
      "latitude": 48.8566,
      "longitude": 2.3522,
      "population": 2161000,
      "needs_postcodes": true,
      "created_at": "2025-12-22T10:00:00Z"
    }
  ],
  "total": 1140,
  "page": 1,
  "page_size": 5,
  "total_pages": 228
}

​
Filter by Population

# Get major French cities (500k+ population)
curl "https://spideriq.di-atomic.com/api/v1/locations?country_code=FR&min_population=500000" \
  -H "Authorization: Bearer <your_token>"
Response: Returns 3 cities (Paris, Marseille, Lyon)

​
Search Locations

curl "https://spideriq.di-atomic.com/api/v1/locations?search=Berlin" \
  -H "Authorization: Bearer <your_token>"

​
Use Cases

  • Preview campaign scope: See which locations match your filter before creating a campaign
  • Find specific locations: Search for cities by name
  • Population analysis: Filter cities by size for targeted campaigns