How  Location Hint works ? How  Location Hint works ?

How Location Hint works ?

Vonage API Support

Applies To

  • Vonage Video API

  • Location Hint

  • Session Creation

  • Routed Sessions

  • Relayed Sessions


Question

How does the Vonage Video API decide where to place the session control server when I create a session? What does the Location Hint parameter do, and how is it different from media routing?


Session Control and Media Routing Are Two Separate Things

This is the most important concept to understand before diving into Location Hint.

A Vonage Video API session involves two completely independent layers:

Layer

What It Does

Controlled By

Session Control (Signalling)

Manages session state, participant join/leave events, and signalling between clients and the platform

Location Hint (optional)

Media Routing

Routes audio and video streams between participants via SFUs (Selective Forwarding Units)

Media Mesh (automatic)

Session control and media routing are independent. Where the session control server is placed has no effect on where media flows, and vice versa. Optimising one does not optimise the other.


How a Session Lands in a Session Control Server

When you create a session using the Vonage Video API REST endpoint, the platform assigns a session control server to manage that session for its entire lifetime. Here is exactly how that placement works in each scenario:

Without a Location Hint

When no location parameter is passed at session creation:

  • When the first participant joins a session, the platform selects a session control server based on the participant's IP address and the platform's internal availability, which typically will be the nearest server to that participant.

  • Participants can still join from anywhere in the world, but signalling may travel a longer distance, which can add latency to session events.

Examples:

Example

First Participant

Server Assigned

Impact

Ex 1

Europe (capacity available)

Europe

All signalling for US participants travels between Europe and the US

Ex 2

India (no capacity in region)

Australia (nearest available)

All signalling for US participants travels to and from Australia


With a Location Hint

When you pass an IP address as the location parameter at session creation:

  • The platform identifies the datacenter geographically closest to that IP address, regardless of the first participant's IP address.

  • The session control server is placed in that datacenter — on a best-effort basis.

  • If the preferred datacenter is at capacity, the platform may fall back to the next closest available datacenter.

Example: You are hosting a webinar where most attendees are in Europe, but you are in the USA. You pass a European IP address as the location hint when creating the session. The platform places the session control server in a European datacenter, reducing signalling latency for your audience.

POST https://api.opentok.com/session/create
location=<european_ip_address>

Note: Location Hint is a preference, not a guarantee. If the closest datacenter is unavailable, the platform will use the next best option.


What Location Hint Does NOT Do

Common Misconception

Reality

Controls where media flows

Location Hint has no effect on media routing

Guarantees media or signalling stays within a specific region

No regional guarantee is provided

Replaces or interacts with Media Mesh

They operate on completely separate layers

Acts as a compliance or data residency tool

Not intended for data residency — use RMZ for media geographic control

Documentation note: The Regional Media Zones guide states: "In addition to restricting media traffic, you can use the EU Proxy feature to restrict non-media traffic to use servers within the European Union." Location Hint is unrelated to this capability.


Session Control vs. Media Routing — Side by Side

Aspect

Session Control (Signalling)

Media Routing (SFU)

What it manages

Session state, participant events, signalling

Audio and video streams

Placement controlled by

Platform availability + first participant's IP or Location Hint

Media Mesh (automatic, always on)

Scope

One server per session

One SFU per participant, independently assigned

Geographic guarantee

No

No (use RMZ for guarantees)

Cost

Free

Free


Best Practices

  • Always pass a Location Hint when you know where the majority of your participants will be joining from — it is free and takes a single parameter.

  • Use a representative IP address from your primary audience's region, not your server's IP, unless your server is co-located with your users.

  • Location Hint is still recommended even when Media Mesh is enabled, since it optimises the signalling layer independently.

  • If you need strict geographic control over both signalling and media, use RMZ — not Location Hint.


Summary

Scenario

Session Control Server Placement

No Location Hint

Platform default — based on availability and the first participant's IP address

Location Hint provided

Closest datacenter to the provided IP — best effort

RMZ enabled

Strictly within the configured RMZ region — hard boundary