List Locations

GET/api/v1/locations

Overview

Query the global location database with various filters. The database contains 44,691 cities across 240 countries.

info

v2.14.0 Feature: The location database is used by the Campaign System to orchestrate multi-location scraping.

Query Parameters

country_codestring

ISO 2-letter country code (e.g., "FR", "DE", "US")

location_typestring

Filter by type: city or postcode

parent_citystring

Filter postcodes by parent city

admin_regionstring

Filter by state/province/region

min_populationinteger

Minimum population filter

max_populationinteger

Maximum population filter

needs_postcodesboolean

Filter big cities needing postcode breakdown

searchstring

Search in display_name or search_string

pageintegerdefault: 1

Page number

page_sizeintegerdefault: 50

Items per page (1-500)

Response

locationsarray

Array of location objects

Location Properties

location_idinteger

Unique identifier

country_codestring

ISO 2-letter country code

country_namestring

Full country name

search_stringstring

Full search string for Google Maps

location_typestring

city or postcode

display_namestring

Human-readable name

parent_citystring

Parent city (for postcodes)

admin_regionstring

State/province/region

latitudenumber

Latitude coordinate

longitudenumber

Longitude coordinate

populationinteger

City population

needs_postcodesboolean

Large city flag

created_atstring

Creation timestamp

totalinteger

Total matching locations

pageinteger

Current page

page_sizeinteger

Items per page

total_pagesinteger

Total pages

Examples

List French Cities

cURL

curl "https://spideriq.ai/api/v1/locations?country_code=FR&page_size=5" \
  -H "Authorization: Bearer <your_token>"

Python

import requests

response = requests.get(
    "https://spideriq.ai/api/v1/locations",
    headers={"Authorization": "Bearer <your_token>"},
    params={"country_code": "FR", "page_size": 5}
)
result = response.json()

print(f"Total French locations: {result['total']}")
for loc in result['locations']:
    print(f"  {loc['display_name']} (pop: {loc['population']:,})")

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.ai/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.ai/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