Geo

Look up the markets (regions), cities and languages D2TR covers.

The Geo endpoints expose the countries, cities and languages that D2TR maintains Discover profiles for, backed by our profile data plus ISO reference tables. They all require an API key and honour the key’s market allowlist: list endpoints are filtered to your allowed countries, and single-region lookups return 403 for a country outside it. Paths are documented under /v1/geo/*; the identical router is also mounted at /v2/geo/* with the same behaviour.

#List regions

GET/v1/geo/regionsAPI key

List the regions (countries) that have Discover profiles. Results are sorted by name and filtered to your key’s allowed countries; total reflects the count after that filtering.

Query parameters

active_onlybooleanoptionaldefault false: Keep only regions with at least one active Discover profile.
with_statsbooleanoptionaldefault false: Attach a stats block (population, internet population, mobile-Chrome population, total estimated Discover impressions/day) when the country has population data.
entitystringoptionaldefault null: A Knowledge Graph id (/m/...) or normalized entity name. Annotates each region with has_entity_activity and entity_impressions for that entity.
windowstringoptionaldefault 24h: Impression window for the entity-activity check. One of 1h, 24h, 7d, 30d.
entity_onlybooleanoptionaldefault false: When entity is set, drop regions with no activity instead of just annotating them.

curl

curl "https://d2tr.com/api/v1/geo/regions?active_only=true&with_stats=true" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "regions": [
    {
      "alpha_2": "US",
      "name": "United States of America",
      "region": "Americas",
      "sub_region": "Northern America",
      "languages": ["en"],
      "cities_count": 12,
      "profiles_count": 3,
      "is_active": true,
      "stats": {
        "population": 331000000,
        "internet_population": 300000000,
        "mobile_chrome_population": 180000000,
        "total_discover_impressions_per_day": 540000000
      },
      "has_entity_activity": true,
      "entity_impressions": 40213
    },
    "…"
  ],
  "total": 9
}

#Get a region

GET/v1/geo/regions/{alpha_2}API key

Fetch details for a single region — its ISO codes, languages, cities and population stats.

Path parameters

alpha_2stringrequired: ISO 3166-1 alpha-2 country code. Uppercased server-side, so us and US both resolve to US.

curl

curl "https://d2tr.com/api/v1/geo/regions/US" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "alpha_2": "US",
  "alpha_3": "USA",
  "name": "United States of America",
  "region": "Americas",
  "sub_region": "Northern America",
  "languages": ["en"],
  "cities": [
    { "id": 101, "name": "New York", "is_active": true },
    { "id": 102, "name": "Los Angeles", "is_active": true }
  ],
  "stats": {
    "alpha_2": "us",
    "population": 331000000,
    "internet_population": 300000000,
    "…": "…"
  },
  "total_articles": 0,
  "articles_last_24h": 0,
  "first_data_at": "2025-01-14T08:22:10+00:00"
}

#List cities in a region

GET/v1/geo/regions/{alpha_2}/citiesAPI key

List the cities tracked within a region. If the region has no profiles, the response is an empty cities array.

Path parameters

alpha_2stringrequired: ISO 3166-1 alpha-2 code (uppercased server-side).

Query parameters

active_onlybooleanoptionaldefault false: Keep only active cities.

curl

curl "https://d2tr.com/api/v1/geo/regions/US/cities?active_only=true" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "region": "US",
  "cities": [
    { "id": 101, "name": "New York", "is_active": true },
    { "id": 102, "name": "Los Angeles", "is_active": true }
  ]
}

#List languages

GET/v1/geo/languagesAPI key

List the languages derived from our Discover profiles, each with the regions it is served in. The language list itself is not region-filtered by your key. Results are sorted by language code ascending.

Query parameters

with_article_countsbooleanoptionaldefault false: Attach an exact article_count (count of urls in that language). This adds one count query per language, so it is slower.

curl

curl "https://d2tr.com/api/v1/geo/languages?with_article_counts=true" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "languages": [
    {
      "code": "en",
      "name": "English",
      "regions": ["AU", "GB", "US"],
      "article_count": 1204331
    },
    {
      "code": "es",
      "name": "Spanish",
      "regions": ["ES", "MX"],
      "article_count": 402118
    },
    "…"
  ]
}