Reference values

Several fields on POST /v1/domains/{domain_uuid}/keywords — and on the search_engines entries inside it — don't take free text. They take values from a fixed catalogue: a search engine name, a location id, a language code, a device, and a check frequency. Send a value outside the catalogue and the API rejects the whole request with 422 Unprocessable Entity (see Errors & rate limits).

Values are matched against the catalogue, not against free text. frequency, name, device and language are matched case-insensitively with surrounding whitespace ignored, so Google, Desktop, FR and zh-cn are accepted and normalised to the canonical forms listed here (google, desktop, fr, zh-CN). Send the canonical form anyway — it is what the API returns in every keyword response. location takes either a Google Ads geo-target id or an ISO 3166-1 alpha-2 country code (see Location). A name is never accepted where a code belongs: "French" for a language or "Dijon, France" for a location is rejected with a 422 that tells you which field failed and which lookup below returns the right value (see Errors & rate limits).

Everything on this page can be read from the API itself with two lookup endpoints, so you do not have to keep a copy of these tables:

Endpoint	Returns
GET /v1/locations	The location catalogue for one search engine — the code of each row is the value to send as search_engines[].location.
GET /v1/languages	The language catalogue for one search engine — the code of each row is the value to send as search_engines[].language.

Both are authenticated like every other /v1 endpoint (a missing or invalid key returns 401 with an empty body; a plan without API access returns 403), both are paginated (see Pagination), and neither is account-scoped — the catalogue is the same for every account. Only search_engines[].name, device and frequency have no lookup: their allowed values are the short lists below, and a 422 for any of them echoes the full list in meta.allowed.

Search engines

search_engines[].name accepts:

• google
• bing
• yahoo

Each engine has its own location and language catalogue, and bing and yahoo cover far fewer of both than google:

Engine	Countries	Languages
google	212	128
bing	180	49
yahoo	84	37

Bing's language codes: ar, bg, ca, cs, da, de, el, en, en-GB, es, et, eu, fi, fr, gl, gu, he, hi, hr, hu, is, it, ja, kn, ko, lt, lv, mr, ms, nb, nl, no, pa, pl, pt-BR, pt-PT, ro, ru, sk, sl, sv, ta, te, th, tr, uk, vi, zh-CN, zh-TW.

Yahoo's language codes: ar, bg, ca, cs, da, de, el, en, es, et, fa, fi, fr, he, hr, hu, id, is, it, ja, ko, lt, lv, nl, no, pl, pt, ro, ru, sk, sl, sv, th, tr, vi, zh-CN, zh-TW.

Yahoo's list is a subset of the Google language list below. Bing's is too, except for two Bing-only codes: en-GB and nb.

Devices

search_engines[].device accepts:

• desktop
• mobile

Frequencies

frequency accepts:

• daily
• weekly
• biweekly (aliases bi-weekly and bi_weekly are also accepted, and are normalised to biweekly)
• monthly

Location

search_engines[].location is not a place name. It accepts two forms, both sent as a JSON string (the OpenAPI schema declares it type: string — always quote it):

• A Google Ads geo-target criteria id, e.g. "2840" (United States), "2250" (France) or "1005850" (Dijon). This is the same id space as Google's own geo targets list — the Criteria ID column there is exactly the value this field expects, for google, bing, and yahoo alike. Cities, regions, postal codes and countries all use this form.
• An ISO 3166-1 alpha-2 country code, e.g. "FR", for country-wide tracking. The API resolves it to the engine's Country row for that country and stores that row's id, so "FR" and "2250" create identical keywords and the keyword's location.code reads back as 2250. The code is case-insensitive ("fr" works), but only the two-letter form is accepted — "FRA" and "France" are rejected.

A location name such as "United States" or "Dijon, France" is rejected with a 422 — it is not resolved to an id for you, because names are ambiguous (the catalogue holds thousands of same-named places) and a wrong guess would bill you for the wrong SERP. The 422 points you at the lookup below, with the first segment of your value pre-filled as the search term.

Looking up a location

GET /v1/locations lists the catalogue for one search engine. Every filter is optional and they combine; a request with none of country, code or q defaults to variant=Country, so a bare GET /v1/locations is the list of countries (212 for google) rather than page 1 of the whole catalogue.

Query parameter	Meaning
search_engine	google (default), bing or yahoo. Case-insensitive. Anything else is a 422 invalid_reference_value listing the three in meta.allowed.
country	ISO 3166-1 alpha-2 country code, case-insensitive (FR, us). Keeps only rows in that country. A country name or a three-letter code is a 422 invalid_reference_value.
variant	Exact, case-sensitive catalogue variant: Country, City, Region, Postal Code, Department, District, Neighborhood, Municipality, Airport, University, …
code	Exact geo-target id, to read one row back (code=1005850). This is the id only — for the ISO form use country=FR&variant=Country.
q	Prefix search on the canonical City,Region,Country name, case-insensitive, 2 to 100 characters after trimming. q=Dijon matches Dijon,Bourgogne-Franche-Comte,France; q=D is a 422 validation_failed (q must be at least 2 characters).
page, per_page	Standard pagination — per_page defaults to 100, max 1000. Totals come back in the X-Total-Count, X-Total-Pages, X-Per-Page and X-Current-Page headers.

Narrow with country whenever you can: country=FR on its own returns every French row (over 8,000 postal codes, cities, departments and regions), so pair it with q for a city or with variant=Country for the single country row. Every filter (search_engine, country, variant, code, q) must be a plain string — q[]=Dijon is a 422 validation_failed (q must be a string); page and per_page are never an error: a non-numeric page is treated as 1, an empty per_page uses the default 100, and any other per_page is clamped into 1–1000 (a non-numeric one counts as 1). Rows are ordered by their catalogue id, oldest first.

curl "https://api.ranktracker.com/v1/locations?search_engine=google&country=FR&q=Dijon" \
  -H "Authorization: tkn_usr_your_api_key_here"

HTTP/1.1 200 OK
Content-Type: application/json
X-Total-Count: 1
X-Total-Pages: 1
X-Per-Page: 100
X-Current-Page: 1

{
  "data": [
    {
      "id": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
      "type": "location",
      "attributes": {
        "code": "1005850",
        "name": "Dijon,Bourgogne-Franche-Comte,France",
        "codeParent": "9068895",
        "countryIsoCode": "FR",
        "variant": "City",
        "formattedName": "Dijon, Bourgogne-Franche-Comte, France",
        "searchEngine": "google"
      }
    }
  ]
}

Attribute	Meaning
code	The geo-target id — the value to send as search_engines[].location.
name	The canonical City,Region,Country name, exactly as q matches it and as keyword responses return it in location.name.
formattedName	name with a space after each comma, for display.
codeParent	The geo-target id of the enclosing location, or null for a top-level row.
countryIsoCode	ISO 3166-1 alpha-2 code of the row's country.
variant	The catalogue variant (Country, City, Postal Code, …).
searchEngine	The engine this row belongs to.

Copy code into your keyword request:

{
  "frequency": "monthly",
  "words": ["agence seo dijon"],
  "search_engines": [
    { "name": "google", "location": "1005850", "language": "fr", "device": "desktop" }
  ]
}

If you would rather not call the endpoint, two other sources give the same ids:

1. Google's geo-targets CSV from the link above — read off the Criteria ID for the country, region, or city you want. This is the authoritative source and covers every id in the catalogue below.
2. An existing keyword. If your account already tracks a keyword in the place you want, GET /v1/domains/{uuid}/keywords returns that keyword's location object, including its code (the id) — copy it for new keywords in the same place. See Pull rankings into a warehouse for the shape of that response.

Worked example: French cities

City ids follow the same pattern — each of these is one row of GET /v1/locations?search_engine=google&country=FR&q=<city>. The City column is the location's full name as the API returns it in location.name, and Location id is the value to send as search_engines[].location:

City	Location id
Bordeaux,Nouvelle-Aquitaine,France	1005811
Dijon,Bourgogne-Franche-Comte,France	1005850
Lille,Hauts-de-France,France	1006235
Lyon,Auvergne-Rhone-Alpes,France	1006410
Marseille,Provence-Alpes-Cote d'Azur,France	1006356
Nantes,Pays de la Loire,France	1006285
Paris,Paris,Ile-de-France,France	1006094
Toulouse,Occitanie,France	1006219

Country-level ids (like 2250 for all of France, or 2840 for all of the United States) are in the country table below.

Languages

search_engines[].language is a language code (fr, en, zh-CN), never a language name — "French" is rejected with a 422. Codes are matched case-insensitively (FR → fr, zh-cn → zh-CN). The Global pseudo-language 0000, which the Ranktracker app can select, cannot be tracked through the API and is rejected with its own 422 message.

Looking up a language

GET /v1/languages lists the codes one search engine accepts. search_engine works exactly as on /v1/locations (google by default); q is optional and, after trimming, must be 1 to 100 characters. It matches either the exact code (case-insensitive) or a substring of the name, so q=fr returns French — and also Afrikaans and Frisian, whose names contain fr. Rows are ordered by code, 0000 is never listed, and pagination is the same page / per_page and X-Total-* headers as every other list.

curl "https://api.ranktracker.com/v1/languages?search_engine=google&q=fr" \
  -H "Authorization: tkn_usr_your_api_key_here"

{
  "data": [
    { "id": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a01", "type": "language", "attributes": { "code": "af", "name": "Afrikaans", "searchEngine": "google" } },
    { "id": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a02", "type": "language", "attributes": { "code": "fr", "name": "French", "searchEngine": "google" } },
    { "id": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a03", "type": "language", "attributes": { "code": "fy", "name": "Frisian", "searchEngine": "google" } }
  ]
}

code is the value to send as search_engines[].language. Use the full name (q=French) when you want a single row: a code is also matched as a substring of names, so q=fr returns the three rows above.

Language codes (google)

search_engines[].language for name: "google" accepts the following codes:

Language	Language code
Afrikaans	af
Akan	ak
Albanian	sq
Amharic	am
Arabic	ar
Armenian	hy
Azeri	az
Balinese	ban
Basque	eu
Belarusian	be
Bengali	bn
Bosnian	bs
Bulgarian	bg
Burmese	my
Catalan	ca
Cebuano	ceb
Chichewa	ny
Chinese (Simplified)	zh-CN
Chinese (Traditional)	zh-TW
Croatian	hr
Czech	cs
Danish	da
Dutch	nl
English	en
Espanol (Latinoamerica)	es-419
Estonian	et
Ewe	ee
Faroese	fo
Farsi	fa
Filipino	fil
Finnish	fi
French	fr
Frisian	fy
Ga	gaa
Galician	gl
Ganda	lg
Georgian	ka
German	de
Greek	el
Gujarati	gu
Haitian	ht
Hausa	ha
Hebrew	he
Hebrew (old)	iw
Hindi	hi
Hungarian	hu
Icelandic	is
IciBemba	bem
Igbo	ig
Indonesian	id
Irish	ga
Italian	it
Japanese	ja
Kannada	kn
Kazakh	kk
Khmer	km
Kinyarwanda	rw
Kirundi	rn
Kongo	kg
Korean	ko
Kreol morisien	mfe
Kreol Seselwa	crs
Krio	kri
Kurdish	ckb
Kyrgyz	ky
Lao	lo
Latvian	lv
Lingala	ln
Lithuanian	lt
Luo	ach
Macedonian	mk
Malagasy	mg
Malay	ms
Malayam	ml
Maltese	mt
Maori	mi
Marathi	mr
Mongolian	mn
Montenegro	sr-ME
Nepali	ne
Northern Sotho	nso
Norwegian	no
Nyankole	nyn
Oromo	om
Pashto	ps
Pidgin	pcm
Polish	pl
Portuguese	pt
Portuguese (Brazil)	pt-BR
Portuguese (Portugal)	pt-PT
Punjabi	pa
Quechua	qu
Romanian	ro
Romansh	rm
Russian	ru
Serbian	sr
Serbian (Latin)	sr-Latn
Sesotho	st
Shona	sn
Silozi	loz
Sindhi	sd
Sinhalese	si
Slovak	sk
Slovenian	sl
Somali	so
Spanish	es
Swahili	sw
Swedish	sv
Tagalog	tl
Tajik	tg
Tamil	ta
Telugu	te
Thai	th
Tigrinya	ti
Tonga (Tonga Islands)	to
Tshiluba	lua
Tswana	tn
Tumbuka	tum
Turkish	tr
Turkmen	tk
Ukrainian	uk
Urdu	ur
Uzbek	uz
Vietnamese	vi
Wolof	wo
Xhosa	xh
Yoruba	yo
Zulu	zu

Countries (google)

Country-level location ids for name: "google". Either column works as search_engines[].location: the Location id ("2250") or the ISO 3166-1 alpha-2 code ("FR"), which the API resolves to that same id. GET /v1/locations?search_engine=google returns this table live.

Country	ISO 3166-1 alpha-2	Location id
Afghanistan	AF	2004
Albania	AL	2008
Algeria	DZ	2012
American Samoa	AS	2016
Andorra	AD	2020
Angola	AO	2024
Antarctica	AQ	2010
Antigua and Barbuda	AG	2028
Argentina	AR	2032
Armenia	AM	2051
Australia	AU	2036
Austria	AT	2040
Azerbaijan	AZ	2031
Bahrain	BH	2048
Bangladesh	BD	2050
Barbados	BB	2052
Belgium	BE	2056
Belize	BZ	2084
Benin	BJ	2204
Bhutan	BT	2064
Bolivia	BO	2068
Bosnia and Herzegovina	BA	2070
Botswana	BW	2072
Brazil	BR	2076
Brunei	BN	2096
Bulgaria	BG	2100
Burkina Faso	BF	2854
Burundi	BI	2108
Cabo Verde	CV	2132
Cambodia	KH	2116
Cameroon	CM	2120
Canada	CA	2124
Caribbean Netherlands	BQ	2535
Central African Republic	CF	2140
Chad	TD	2148
Chile	CL	2152
China	CN	2156
Christmas Island	CX	2162
Cocos (Keeling) Islands	CC	2166
Colombia	CO	2170
Comoros	KM	2174
Cook Islands	CK	2184
Costa Rica	CR	2188
Cote d'Ivoire	CI	2384
Croatia	HR	2191
Curacao	CW	2531
Cyprus	CY	2196
Czechia	CZ	2203
Democratic Republic of the Congo	CD	2180
Denmark	DK	2208
Djibouti	DJ	2262
Dominica	DM	2212
Dominican Republic	DO	2214
Ecuador	EC	2218
Egypt	EG	2818
El Salvador	SV	2222
Equatorial Guinea	GQ	2226
Eritrea	ER	2232
Estonia	EE	2233
Eswatini	SZ	2748
Ethiopia	ET	2231
Fiji	FJ	2242
Finland	FI	2246
France	FR	2250
French Polynesia	PF	2258
French Southern and Antarctic Lands	TF	2260
Gabon	GA	2266
Georgia	GE	2268
Germany	DE	2276
Ghana	GH	2288
Greece	GR	2300
Grenada	GD	2308
Guam	GU	2316
Guatemala	GT	2320
Guernsey	GG	2831
Guinea	GN	2324
Guinea-Bissau	GW	2624
Guyana	GY	2328
Haiti	HT	2332
Heard Island and McDonald Islands	HM	2334
Honduras	HN	2340
Hungary	HU	2348
Iceland	IS	2352
India	IN	2356
Indonesia	ID	2360
Iraq	IQ	2368
Ireland	IE	2372
Isle of Man	IM	2833
Israel	IL	2376
Italy	IT	2380
Jamaica	JM	2388
Japan	JP	2392
Jersey	JE	2832
Jordan	JO	2400
Kazakhstan	KZ	2398
Kenya	KE	2404
Kiribati	KI	2296
Kuwait	KW	2414
Kyrgyzstan	KG	2417
Laos	LA	2418
Latvia	LV	2428
Lebanon	LB	2422
Lesotho	LS	2426
Liberia	LR	2430
Libya	LY	2434
Liechtenstein	LI	2438
Lithuania	LT	2440
Luxembourg	LU	2442
Madagascar	MG	2450
Malawi	MW	2454
Malaysia	MY	2458
Maldives	MV	2462
Mali	ML	2466
Malta	MT	2470
Marshall Islands	MH	2584
Mauritania	MR	2478
Mauritius	MU	2480
Mexico	MX	2484
Micronesia	FM	2583
Moldova	MD	2498
Monaco	MC	2492
Mongolia	MN	2496
Montenegro	ME	2499
Morocco	MA	2504
Mozambique	MZ	2508
Myanmar (Burma)	MM	2104
Namibia	NA	2516
Nauru	NR	2520
Nepal	NP	2524
Netherlands	NL	2528
New Caledonia	NC	2540
New Zealand	NZ	2554
Nicaragua	NI	2558
Niger	NE	2562
Nigeria	NG	2566
Niue	NU	2570
Norfolk Island	NF	2574
Northern Mariana Islands	MP	2580
North Macedonia	MK	2807
Norway	NO	2578
Oman	OM	2512
Pakistan	PK	2586
Palau	PW	2585
Panama	PA	2591
Papua New Guinea	PG	2598
Paraguay	PY	2600
Peru	PE	2604
Philippines	PH	2608
Pitcairn Islands	PN	2612
Poland	PL	2616
Portugal	PT	2620
Qatar	QA	2634
Republic of the Congo	CG	2178
Romania	RO	2642
Rwanda	RW	2646
Saint Helena, Ascension and Tristan da Cunha	SH	2654
Saint Kitts and Nevis	KN	2659
Saint Lucia	LC	2662
Saint Pierre and Miquelon	PM	2666
Saint Vincent and the Grenadines	VC	2670
Samoa	WS	2882
San Marino	SM	2674
Sao Tome and Principe	ST	2678
Saudi Arabia	SA	2682
Senegal	SN	2686
Serbia	RS	2688
Seychelles	SC	2690
Sierra Leone	SL	2694
Singapore	SG	2702
Sint Maarten	SX	2534
Slovakia	SK	2703
Slovenia	SI	2705
Solomon Islands	SB	2090
Somalia	SO	2706
South Africa	ZA	2710
South Georgia and the South Sandwich Islands	GS	2239
South Korea	KR	2410
Spain	ES	2724
Sri Lanka	LK	2144
Suriname	SR	2740
Sweden	SE	2752
Switzerland	CH	2756
Tajikistan	TJ	2762
Tanzania	TZ	2834
Thailand	TH	2764
The Bahamas	BS	2044
The Gambia	GM	2270
Timor-Leste	TL	2626
Togo	TG	2768
Tokelau	TK	2772
Tonga	TO	2776
Trinidad and Tobago	TT	2780
Tunisia	TN	2788
Turkiye	TR	2792
Turkmenistan	TM	2795
Tuvalu	TV	2798
Uganda	UG	2800
Ukraine	UA	2804
United Arab Emirates	AE	2784
United Kingdom	GB	2826
United States	US	2840
United States Minor Outlying Islands	UM	2581
Uruguay	UY	2858
Uzbekistan	UZ	2860
Vanuatu	VU	2548
Vatican City	VA	2336
Venezuela	VE	2862
Vietnam	VN	2704
Wallis and Futuna	WF	2876
Yemen	YE	2887
Zambia	ZM	2894
Zimbabwe	ZW	2716

---

Catalogue snapshot 2024-08-27.