-
SEO Learning Center
Broaden your SEO knowledge with resources for all skill levels.
-
The Beginner's Guide to SEO
If you're brand new to SEO, start here.
-
SEO Q&A
Get answers from the Moz Community.
-
Free Downloads and More
Quick access to whitepapers, reports, guides, webinars, and case studies.
-
Help Hub
Learn how to use Moz products.
-
Community & Events
Connect with over 600k online marketers.
-
SEO Training
Instructor-led classes and seminars
Data > Keyword > Metrics
Fetch Multiple Keyword Metrics
JSON-RPC Method:
data.keyword.metrics.fetch.multipleRetrieve difficulty, volume, organic CTR, priority, and search intent metrics for up to 50 keywords in a single request. Each keyword must already exist in our database; keywords we have no data for are returned in errors_by_serp_query rather than failing the whole request.
Search intent is always included for supported (English) locales and is null when unavailable for the SERP.
serp_queries
array
keyword
string
The keyword to query. Must be between 1 and 255 characters.
locale
string
The locale to search in, provided as an hl-gl pair - a valid Google hl (host language) value and a valid gl (country) value, joined by a hyphen, e.g. en-US.
device
string
The device to perform the query for.
Acceptable Values:
desktopmobile_androidmobile_iosengine
string
The engine for the query.
Acceptable Values:
googlebingyahoovicinity
string
(Optional)
The location to perform the search from - e.g. New York, NY. This field is optional and defaults to a blank string, which is interpreted as national.
1{
2 "serp_queries": [
3 {
4 "keyword": "seo software",
5 "locale": "en-US",
6 "device": "desktop",
7 "engine": "google",
8 "vicinity": ""
9 },
10 {
11 "keyword": "link building",
12 "locale": "en-US",
13 "device": "desktop",
14 "engine": "google",
15 "vicinity": ""
16 }
17 ]
18}Results are partitioned into `results_by_serp_query` (queries we found metrics for) and `errors_by_serp_query` (queries that could not be resolved, e.g. a keyword we have no data for). Both arrays echo the parsed `serp_query`, so entries can be correlated back to the request.
results_by_serp_query
array
serp_query
object
Represents a SERP query object.
keyword_metrics
object
Available metrics for a given keyword. If a value is null, it could not be calculated when the keyword was last collected.
errors_by_serp_query
array
serp_query
object
Represents a SERP query object.
error
object
An error returned from the API.
1{
2 "results_by_serp_query": [
3 {
4 "serp_query": {
5 "keyword": "seo software",
6 "locale": "en-US",
7 "device": "desktop",
8 "engine": "google",
9 "vicinity": ""
10 },
11 "keyword_metrics": {
12 "volume": 8100,
13 "difficulty": 62,
14 "organic_ctr": 34,
15 "priority": 71,
16 "intent": {
17 "primary_intents": [
18 "commercial"
19 ],
20 "all_intents": [
21 {
22 "label": "commercial",
23 "score": 0.58
24 },
25 {
26 "label": "informational",
27 "score": 0.21
28 },
29 {
30 "label": "transactional",
31 "score": 0.13
32 },
33 {
34 "label": "navigational",
35 "score": 0.08
36 }
37 ]
38 }
39 }
40 }
41 ],
42 "errors_by_serp_query": [
43 {
44 "serp_query": {
45 "keyword": "link building",
46 "locale": "en-US",
47 "device": "desktop",
48 "engine": "google",
49 "vicinity": ""
50 },
51 "error": {
52 "message": "That query was not found.",
53 "name": "NotFoundError",
54 "data": {
55 "key": "serp_queries.1.keyword",
56 "value": "link building"
57 },
58 "httpStatus": 404,
59 "jsonrpcCode": -32655
60 }
61 },
62 {
63 "serp_query": {
64 "keyword": "another keyword",
65 "locale": "en-US",
66 "device": "desktop",
67 "engine": "google",
68 "vicinity": ""
69 },
70 "error": {
71 "message": "An unexpected error occurred.",
72 "name": "UnhandledError",
73 "data": {
74 "key": "serp_queries.2.keyword",
75 "value": "another keyword"
76 },
77 "httpStatus": 500,
78 "jsonrpcCode": -32602
79 }
80 }
81 ]
82}Uses one row per returned metric value, for a max of 5 per result. Any unavailable (null) values are discounted from the total row usage, and queries returned in errors_by_serp_query are not charged.
api.limits.data.rows