Location Statistics

GET/api/v1/locations/stats

Overview

Retrieve comprehensive statistics about the global location database, including total counts and top countries by location count.

Response

total_locationsinteger

Total locations in database

total_countriesinteger

Number of countries covered

total_citiesinteger

Number of city-type locations

total_postcodesinteger

Number of postcode-type locations

cities_needing_postcodesinteger

Large cities that could benefit from postcode breakdown

top_countriesarray

Top 20 countries by location count

Country Statistics

country_codestring

ISO code

country_namestring

Full name

total_locationsinteger

Location count

citiesinteger

City count

postcodesinteger

Postcode count

needs_postcodesinteger

Large cities count

Example

cURL

curl https://spideriq.ai/api/v1/locations/stats \
  -H "Authorization: Bearer <your_token>"

Python

import requests

response = requests.get(
    "https://spideriq.ai/api/v1/locations/stats",
    headers={"Authorization": "Bearer <your_token>"}
)
stats = response.json()

print(f"Total locations: {stats['total_locations']:,}")
print(f"Countries: {stats['total_countries']}")
print(f"Cities: {stats['total_cities']:,}")
print(f"\nTop 5 countries:")
for country in stats['top_countries'][:5]:
    print(f"  {country['country_name']}: {country['total_locations']:,} locations")

Response:

{
  "total_locations": 44691,
  "total_countries": 240,
  "total_cities": 44691,
  "total_postcodes": 0,
  "cities_needing_postcodes": 1438,
  "top_countries": [
    {
      "country_code": "US",
      "country_name": "United States",
      "total_locations": 5123,
      "cities": 5123,
      "postcodes": 0,
      "needs_postcodes": 287
    },
    {
      "country_code": "DE",
      "country_name": "Germany",
      "total_locations": 2108,
      "cities": 2108,
      "postcodes": 0,
      "needs_postcodes": 14
    },
    {
      "country_code": "FR",
      "country_name": "France",
      "total_locations": 1140,
      "cities": 1140,
      "postcodes": 0,
      "needs_postcodes": 12
    }
  ]
}

Data Source

The location database is sourced from SimpleMaps World Cities dataset, containing cities with population data for accurate campaign planning.