Skip to content
Metadata API · Use case

Fetch localized metadata as a visitor in another country sees it

Localized metadata is what a visitor in a given country actually sees: the translated title, the local currency, the regional availability. A preview generated from a US datacenter shows the US version to everyone. Pin the Metadata API request to the visitor’s country and language and the response matches their view, which is what price monitors, travel and retail aggregators and international newsletters need.

Start with the Metadata API
The problem

Websites localize their metadata, extractors do not

Stores show local currency, publishers translate titles, and some pages redirect to a regional domain based on where the request comes from. An extractor with one exit country reports one version of the truth, and it is rarely the one your user in Berlin or Tokyo sees.

Setting Accept-Language alone does not fix it, because geo-targeting reads the origin IP rather than a header. Running your own servers or proxies in every market is the other option, and it turns a metadata call into infrastructure you maintain per country.

proxy.location routes the request through a proxy IP in the country you choose, headers adds the Accept-Language the site negotiates on, and a data rule captures a localized value such as the price. Each combination is cached separately.

How it works

How to fetch metadata from another country

Two request options localize the page, and a rule reads the value that differs. Both options are part of Pro plans, as the proxy guide explains.

1 · Metadata as seen from a country
import createClient from 'microlink.io'

const microlink = createClient({
  apiKey: process.env.MICROLINK_API_KEY
})

const { title, description } = await microlink.metadata('https://example.com/product', {
  proxy: { location: 'de' }
})

The request exits from a German IP, so the site serves its German-region version and the normalized title and description come from that version.

2 · Add the language and the local price
import createClient from 'microlink.io'

const microlink = createClient({
  apiKey: process.env.MICROLINK_API_KEY
})

const { title, price } = await microlink.metadata('https://example.com/product', {
  proxy: { location: 'de' },
  headers: { 'Accept-Language': 'de-DE' },
  data: {
    price: { selector: '.price', attr: 'text' }
  }
})

The language header completes the localization, and the rule captures the price text exactly as displayed, currency symbol included.

3 · The same request as a URL
curl 'https://pro.microlink.io/?url=https%3A%2F%2Fexample.com%2Fproduct&proxy.location=de&headers.Accept-Language=de-DE' \
  -H 'x-api-key: $MICROLINK_API_KEY'

proxy.location and headers are Pro options, so the URL targets pro.microlink.io. Header values in the query string are public, so keep them to non-sensitive ones such as Accept-Language.

Parameters used
  • proxy.location ISO 3166-1 alpha-2 country code, case-insensitive. Default us. Exclusive with proxy.url. Pro plans.
  • headers Forwards Accept-Language and other non-sensitive headers to the target. Pro plans.
  • data A rule for the localized value the normalized fields do not carry, such as the price.
  • cacheKey Extra separation when the same URL must be cached per audience. Pro plans.

Verify the exit country first: request https://geolocation.microlink.io with the same proxy.location and it returns the IP and the country the target sees. An unknown country code is rejected with EINVALQUERY.

Why it works

Why a price-by-country lookup needs a real exit IP

Sites decide the region from the IP. Only a request from that region gets that region’s metadata.

01 · IP-based region
proxy.location makes the request come from there.
Geo-targeting reads the origin IP. A proxy exit in the target country is the only way to be served that version, and it is one option on the request rather than a server you run in each market.

The same exit works for the visual side of the job: see screenshots from another country.

02 · Header-based language
Accept-Language completes the picture.
Many sites pick the region from the IP and the language from the header. Setting both returns titles and descriptions in the local language, with the local currency.

Keep secrets out of the headers parameter, because it travels in the query string. Cookies and tokens go in x-api-header-* request headers instead.

03 · Cached per audience
Each country and language pair is its own entry.
The cache key is derived from the URL and every recognized parameter, so the German and the Japanese versions of a page never overwrite each other. Cache hits do not count against your quota.

When not to: sites that localize only from the browser language need just the header, without a proxy. Check which signal the target uses before you route every request through a country.

FAQ

Can I get metadata as a visitor from a specific country would see it?

Yes. Pass proxy.location with the two-letter country code on a Pro plan and the request is routed through a proxy IP in that country. The normalized title, description and image then come from the version of the page served to that region.

Which countries can a localized metadata request exit from?

proxy.location accepts ISO 3166-1 alpha-2 country codes, and the location reference lists every supported one. The value is case-insensitive and defaults to us. Unknown codes are rejected with EINVALQUERY.

Does proxy.location also translate the page metadata?

Only if the site derives the language from the IP. Sites that negotiate language from the browser also need the Accept-Language header, passed through the headers parameter. Send both when you are not sure which signal the target uses.

Are localized link previews cached separately per country?

Yes. Different proxy.location or header values produce different cache keys, so each market keeps its own entry for 24 hours by default. Add cacheKey on Pro plans when you need an extra namespace.

How do I capture the local price next to the metadata?

Add a data rule that targets the price element, for example selector .price with attr text. It comes back next to the normalized fields, in the currency the site shows to that country. See custom fields alongside metadata for typed rules and lists.
Related use cases

Solve the next problem with the same API

Link previews for bot-protected sites

Unfurl links to sites behind Cloudflare or DataDome by routing the metadata request through the built-in proxy.
Preview bot-protected sites 

Custom fields alongside metadata

Get prices, ratings, headings or any CSS selector, typed and returned next to the normalized metadata.
Extract custom fields 

Screenshot a site from another country

Pin the request to a country with a two-letter code and capture the prices and copy a local visitor sees.
Capture from another country 

Ready for localized metadata?

Titles, descriptions and prices as each market sees them. Get a Pro key and fetch your first regional version today.

Fetch localized metadata