How do Nozzle locales work?

A locale in Nozzle is a single ID that identifies where and how a keyword should be tracked — the country, the city (if applicable), the language, and the device. One ID, one tracking configuration.

If you've used Google's Keyword Planner or Ads APIs, you've probably worked with criteria_id (Google's location identifier) and language_code as a pair. Nozzle locales bundle those together with device into a single number — so you reference one localeId instead of three separate values.

This guide covers what locales are, how to find the one you need, and what to do when the locale you want doesn't exist yet.

Why a single ID instead of three values?

Google's criteria_id identifies a location (e.g., 1019760 for Vienna, Austria). To search from that location in a specific language on a specific device, you need all three pieces. Different combinations behave differently — searching in Vienna in German on mobile is a different query than searching in Vienna in English on desktop.

Nozzle pre-builds a localeId for each useful combination. That way, when you tell Nozzle to track "tokyo station luggage storage" with localeId: 18995, there's no ambiguity about which language, which city, or which device — it's all baked into the ID.

The trade-off: not every theoretical combination of (criteria_id, language, device) exists in Nozzle's catalog by default. Most common ones do. Less common ones may need to be added — see Adding a missing locale below.

The shape of a locale

Each locale record has the following fields:

You'll see these fields in the BigQuery latest_keywords_by_keyword_id table and in API responses for keyword sources.

Finding the locale you need

There are three ways, depending on your situation.

1. Look it up in BigQuery

If you have BigQuery access, the latest_keywords_by_keyword_id table has every locale currently in use across your projects, with all the fields above:

SELECT DISTINCT
  locale_id,
  country,
  location,
  language,
  device
FROM nozzledata.<workspace>_<project>.latest_keywords_by_keyword_id
WHERE country = 'Japan'
  AND language = 'Japanese'
ORDER BY location

This is the fastest path if you're already a BigQuery user.

2. Use the Nozzle UI

When you create or edit a keyword set in app.nozzle.io, the location and language pickers will surface available locales. The localeId is captured behind the scenes — you don't need to know the number to use it through the UI.

3. Request the catalog from support

If you're building an automated integration and need the full mapping of (criteria_id, language) → localeId, contact us and we'll send you the latest catalog as a CSV.

The catalog is large (well over a million rows — exceeds Excel's row limit) and is updated periodically as we add new combinations.

Adding a missing locale

The locale catalog is comprehensive but not exhaustive. If you try to use a (criteria_id, language) combination that doesn't have a localeId yet, your request will fail.

To add new locales:

1. Contact us with the list of (criteria_id, language_code) pairs you need.
2. Most additions are processed within a few business days.
3. Some criteria_id values aren't recognized by our upstream provider and require additional work — we'll let you know if any of yours fall in that category.

A couple of practical notes:

• Google occasionally has duplicate criteria_id values for the same city. If a criteria_id you're working with isn't in our catalog, check whether Google has an equivalent ID — often there's a more commonly-used variant we already support.
• Languages we don't already track in a location may take longer. If you ask for a language combination we've never tracked anywhere (e.g., a regional language in a country we mainly track in English), the addition may take longer because the upstream data needs to be configured.

Locales in the API: basic vs advanced keyword sources

How locales work in the API depends on which keyword source type you're using.

Basic keyword sources

In a basic keyword source, you provide:

• A list of phrases
• A list of localeIds to track every phrase against
• A list of devices

Nozzle handles the multiplication. If you have 10 phrases and 4 locales, Nozzle tracks all 40 combinations. This is the recommended type whenever it fits — there's no risk of accidentally tracking the wrong phrase in the wrong locale.

{
  "type": "basic",
  "config": {
    "phraseGroups": [
      { "phrase": "running shoes", "groups": null },
      { "phrase": "trail running shoes", "groups": null }
    ],
    "localeIds": [44249, 14964],
    "devices": ["d", "m"]
  }
}

This tracks both phrases in both locales on both devices — 8 keyword combinations total.

Advanced (JSON) keyword sources

In an advanced keyword source, each phrase carries its own list of localeIds and devices. Use this when different phrases need different locale targeting — for example, when you're tracking POI-specific keywords that only make sense in their respective cities.

{
  "type": "json",
  "config": {
    "jsonKeywords": [
      {
        "phrase": "tokyo station luggage storage",
        "localeIds": [18995],
        "devices": ["m"],
        "groups": ["POI tracking"]
      },
      {
        "phrase": "gare du nord luggage storage",
        "localeIds": [168406],
        "devices": ["m"],
        "groups": ["POI tracking"]
      }
    ]
  }
}

This is more flexible but easier to get wrong. Use it when you genuinely need per-phrase locale control; otherwise, stick with basic.

Need help?

If you're stuck on a locale issue — missing combinations, ambiguous criteria IDs, or you're just not sure which localeId to use for a specific search — reach out and include any criteria_id and language codes you're working with. We'll either point you at the right localeId or get the missing combinations added.