Guide

Give your AI access to Portuguese data

Weather, emergencies, fuel prices, companies, invoices, contracts, economic data — all available to your AI assistant in seconds.

What can your AI do with this?

Where's the cheapest diesel near Lisbon?
Searches 3,000+ gas stations and returns the cheapest options with prices, brands, and addresses.
Are there any active emergencies in Portugal right now?
Shows real-time civil protection incidents — fires, floods, accidents — with location, resources deployed, and status.
Tell me everything about this company [photo of invoice]
Reads the invoice, validates the NIF, looks up the company (name, address, business activity, public contracts), and checks the VAT calculation.
What's the weather forecast for Porto this week?
Returns IPMA forecasts with temperature, precipitation, wind, and any active meteorological warnings.
How much EU funding did company X receive?
Cross-references NIF with public contracts from BASE/IMPIC — shows total value and recent contracts.

How to connect

Choose your AI tool and follow the steps. It takes less than a minute.

Claude Code
Terminal / CLI
Ready
Claude Desktop
macOS / Windows app
Ready
Cursor
AI code editor
Ready
Windsurf
AI code editor
Ready
ChatGPT
via Actions / API
Ready
Gemini
via Extensions / API
Ready
Custom agents
Any MCP or REST client
Ready

Claude Code (easiest)

One command in your terminal:

claude mcp add ptdata --transport streamable-http https://api.ptdata.org/mcp

Done. Now just ask Claude anything about Portugal.

Claude Desktop

  1. Open the config file:

    # macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows
%APPDATA%\Claude\claude_desktop_config.json

  2. Add this to the file (or create it if it doesn't exist):

    {
  "mcpServers": {
    "ptdata": {
      "type": "url",
      "url": "https://api.ptdata.org/mcp"
    }
  }
}

  3. Restart Claude Desktop. You'll see the tools icon appear in the chat — that means it's connected.

Cursor / Windsurf / Other editors

Most AI code editors support MCP. Look for "MCP servers" in settings and add:

URL: https://api.ptdata.org/mcp
Transport: Streamable HTTP

No API key needed for public data. If you need authenticated features (invoice submission, accountant platform), register via the API to get a Bearer token.

ChatGPT

Use ChatGPT with the API in two ways:

  1. Custom GPT with Actions: Create a Custom GPT at chat.openai.com, go to "Configure" > "Actions", and import the OpenAPI spec from https://api.ptdata.org/openapi.yaml. ChatGPT will automatically create actions for all 52 endpoints.

  2. Direct in chat: Just paste a curl command or API URL and ask ChatGPT to analyze the result. Example: "Fetch https://api.ptdata.org/v1/civil-protection/occurrences/active and tell me what's happening"

Gemini

Google Gemini can call the API directly:

  1. Gemini Extensions: Use the "Google Search" extension with a prompt like "search api.ptdata.org/v1/weather/warnings and summarize"

  2. Vertex AI / AI Studio: Add the API as a function calling tool using the OpenAPI spec at https://api.ptdata.org/openapi.yaml

Any AI — just paste the URL

Even without MCP, any AI that can browse the web or fetch URLs can use the API. Just ask it:

# Works in any AI chat
"Fetch https://api.ptdata.org/v1/fuel/prices?fuel=gasolina+95&district=11&limit=5
and tell me the cheapest petrol in Lisbon"

Build your own AI agent

Any application that speaks MCP (Model Context Protocol) can connect. The server uses Streamable HTTP transport — just POST JSON-RPC 2.0 to the endpoint:

# List all available tools
curl -X POST https://api.ptdata.org/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Call a tool
curl -X POST https://api.ptdata.org/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_active_occurrences","arguments":{}},"id":2}'

What data is available?

27+ tools across 8 domains, all free:

Geography

20 districts, 308 municipalities, 3,092 parishes, NUTS regions, population data

list_districtsget_districtlist_municipalitiessearch_geo

Civil Protection (real-time)

Active emergencies, historical fire records (ICNF), fire risk index by municipality

get_active_occurrenceslist_firesget_fire_riskget_cp_stats

Weather

IPMA forecasts for 35 cities, 221 station observations, meteorological warnings

get_weather_forecastsget_weather_warningsget_weather_observationsget_weather_stations

Fuel Prices

Real-time prices from 3,000+ gas stations. Find the cheapest fuel near you.

search_fuel_pricesget_fuel_station

Economy

EUR exchange rates (20 currencies), ECB interest rates, CPI/GDP/unemployment, housing prices

get_exchange_ratesget_interest_ratesget_economic_indicatorsget_housing_prices

Companies

Look up any Portuguese company by NIF — name, address, business activity (CAE), VAT status, public contracts

lookup_companyvalidate_nifget_vat_rates

Public Contracts

80,000+ public procurement contracts from BASE/IMPIC with prices, entities, suppliers

search_contractsget_contractget_contract_stats

Invoices & Tax

Validate invoice data (NIF, VAT, totals), submit to AT, format for accountant

validate_invoicesubmit_invoice_to_atformat_invoice_for_accountant

Questions?

Full API documentation · Discovery endpoint · System status

Contact: hello@ptdata.org