Tutorial: BarentsWatch (Maritime)

Transport

Data source: BarentsWatch

Overview

BarentsWatch (Maritime) wraps BarentsWatch, handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-barentswatch": {
      "url": "https://context.gnist.ai/mcp/barentswatch/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`get_vessel`

Get the current position and details for a vessel by MMSI. Args: mmsi: 9-digit Maritime Mobile Service Identity number (e.g. 257338000). Returns: Vessel record with name, flag, type, position, speed, course, destination, and navigational status from live AIS data.

Parameter	Type	Required	Description
`mmsi`	integer	required	9-digit Maritime Mobile Service Identity number (e.g. 257338000).

curl -X POST "https://context.gnist.ai/mcp/barentswatch/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_vessel", "arguments": {"mmsi": 257338000}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/barentswatch/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'mmsi': 257338000}, 'name': 'get_vessel'}},
)
print(resp.json())

`vessels_in_area`

Get all vessels currently in a geographic area. Specify the area as a named port OR as an explicit bounding box. Args: bbox: Comma-separated bounding box 'lon_min,lat_min,lon_max,lat_max'. port_name: Named port (e.g. 'oslo', 'rotterdam', 'singapore', 'hamburg'). lon_min: Bounding box west edge. lat_min: Bounding box south edge. lon_max: Bounding box east edge. lat_max: Bounding box north edge. vessel_type: Filter by type: 'cargo', 'tanker', 'passenger', 'fishing', 'tug'. limit: Maximum vessels to return (1–200, default 50). Returns: Dictionary with count and vessels list.

Parameter	Type	Required	Description
`bbox`	any	optional	Comma-separated bounding box 'lon_min,lat_min,lon_max,lat_max'.
`port_name`	any	optional	Named port (e.g. 'oslo', 'rotterdam', 'singapore', 'hamburg').
`lon_min`	any	optional	Bounding box west edge.
`lat_min`	any	optional	Bounding box south edge.
`lon_max`	any	optional	Bounding box east edge.
`lat_max`	any	optional	Bounding box north edge.
`vessel_type`	any	optional	Filter by type: 'cargo', 'tanker', 'passenger', 'fishing', 'tug'.
`limit`	integer	optional	Maximum vessels to return (1–200, default 50). (default: `50`)

curl -X POST "https://context.gnist.ai/mcp/barentswatch/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "vessels_in_area", "arguments": {"bbox": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/barentswatch/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'bbox': 'example'}, 'name': 'vessels_in_area'}},
)
print(resp.json())

`get_vessel_track`

Get the recent position history (track) for a vessel. Args: mmsi: 9-digit MMSI number. hours: How many hours of history to return (1–168, default 24). Returns: Dictionary with mmsi, name, point_count, and points list (lat, lon, speed, course, timestamp).

Parameter	Type	Required	Description
`mmsi`	integer	required	9-digit MMSI number.
`hours`	integer	optional	How many hours of history to return (1–168, default 24). (default: `24`)

curl -X POST "https://context.gnist.ai/mcp/barentswatch/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_vessel_track", "arguments": {"mmsi": 5}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/barentswatch/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'mmsi': 5}, 'name': 'get_vessel_track'}},
)
print(resp.json())

`search_vessel`

Search for vessels by name (partial match). Args: name_query: Vessel name or partial name (e.g. 'Stena', 'Nordic Eagle'). flag: Optional country filter — ISO 2-letter code (e.g. 'NO', 'NL'). Returns: Dictionary with count and vessels list including MMSI, name, flag, and position.

Parameter	Type	Required	Description
`name_query`	string	required	Vessel name or partial name (e.g. 'Stena', 'Nordic Eagle').
`flag`	any	optional	Optional country filter — ISO 2-letter code (e.g. 'NO', 'NL').

curl -X POST "https://context.gnist.ai/mcp/barentswatch/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_vessel", "arguments": {"name_query": "'Stena'"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/barentswatch/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'name_query': "'Stena'"}, 'name': 'search_vessel'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/barentswatch/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/barentswatch/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_vessel to find items, then get_vessel to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does BarentsWatch (Maritime) provide?

Live AIS vessel tracking — position, speed, course, and voyage data. It exposes 5 tools: get_vessel, vessels_in_area, get_vessel_track, search_vessel, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the BarentsWatch (Maritime) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.