Google News Topic Resolver API

Q: How many inputs can I send?

Exactly one of `place`, `section`, `mid` or `query`. Sending none or more than one is a 400.

Q: How do I spot a place fallback?

Read `resolved.matchedInput`. False means the answer is the U.S. topic fallback an unknown place can resolve to, not a match for the place you asked for. An unknown place can also answer `not_found`. A localised name for a real place is still a match. You can also compare `resolved.mid` with a MID you asked for.

Q: When are candidates returned?

Name resolution through `query` can return `candidates` from the suggestion box. Place, section and MID resolution return an empty list.

Q: What does not_found mean?

Nothing matched. `resolved` is null. Check `input` to confirm which field was resolved.

Turn a place, section, MID or name into the topic or publisher id the other routes take.

GET /v1/google-news/topics/resolve

1 credit Failed requests are free

Try in playground Full API docs

About this endpoint

GET /v1/google-news/topics/resolve takes exactly one of place, section, mid or query. It returns lookupStatus, input, resolved, candidates and edition. resolved has id, kind, name, mid, url and matchedInput, and kind is topic, publisher or unknown.

Use place for a city or place name such as London or San Francisco, CA, section for one of WORLD, NATION, BUSINESS, TECHNOLOGY, ENTERTAINMENT, SPORTS, SCIENCE or HEALTH, and mid for a Knowledge Graph id such as /m/04jpl. query goes through the suggestion box and can return candidates as well as resolved.

A place name can resolve to the U.S. topic, which is where an unknown place can fall back, or be not_found. resolved.matchedInput is false when the answer is that fallback, so an unknown place that resolves to U.S. is visible without decoding the MID. The comparison uses ids, so a local name such as München for Munich still counts as a match. When nothing resolves, lookupStatus is not_found and resolved is null.

Google News Topic Resolver API FAQ

How many inputs can I send?

Exactly one of place, section, mid or query. Sending none or more than one is a 400.

How do I spot a place fallback?

Read resolved.matchedInput. False means the answer is the U.S. topic fallback an unknown place can resolve to, not a match for the place you asked for. An unknown place can also answer not_found. A localised name for a real place is still a match. You can also compare resolved.mid with a MID you asked for.

When are candidates returned?

Name resolution through query can return candidates from the suggestion box. Place, section and MID resolution return an empty list.

What does not_found mean?

Nothing matched. resolved is null. Check input to confirm which field was resolved.

How many credits does it cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged: that field is the billing source of truth.

About this endpoint

Google News Topic Resolver API FAQ

Other Google News endpoints