360 Secure SkillHub
360 安全技能中心

Countries API

该 Skill 说明如何使用 countries.dev 的免鉴权 REST 接口，按 ISO 代码或名称查询国家信息，并支持城市与地名搜索、反向地理编码、邮编查询、IP 归属地判断以及两点距离计算；强调字段筛选、分页参数与端点选用约定，完整端点清单位于 references/endpoints.md。

nanookai
nanookai
热度 24.98
最近更新 2026-07-06 15:49:21
分类：搜索依赖：第三方 API / 代码执行应用场景：API 集成 / 研究 / 旅行 / 数据处理

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add countries-api
Metadata
name
countries-api
description
Query the free countries.dev REST API (no API key needed) for country data (names, capitals, populations, currencies, languages, flags, borders, timezones), city/place search and reverse geocoding, postal/ZIP code lookup, IP geolocation, and distance between locations. Use this skill whenever the user asks about countries, capitals, country codes (ISO alpha-2/alpha-3), currencies by country, national flags, neighbouring countries, city coordinates, "which country is this IP in", ZIP/postal code lookups, or distances between cities — even if they don't mention countries.dev or an API by name.

countries.dev API

A free, no-auth REST API for country, city, postal-code, and IP-geolocation data. Base URL: https://countries.dev

  • No API key, no signup, no documented rate limits. Just send GET requests.
  • All responses are JSON (errors like "Country not found" come back as plain text with a 404 status — always check the HTTP status code).
  • CORS is enabled, so it works from browsers as well as curl/server code.
  • Data sources: country data plus GeoNames (~34k cities, ~12M places, ~1.8M postal codes across ~121 countries).

Quick start

# One country by ISO code (alpha-2 or alpha-3, case-insensitive)
curl https://countries.dev/alpha/JP

# Search by name (substring match, returns an array)
curl "https://countries.dev/name/japan?fields=name,capital,population"

# All countries, top 10 by population
curl "https://countries.dev/countries?fields=name,population&sort=population&order=desc&limit=10"

# Find a city and its coordinates
curl "https://countries.dev/cities?q=taipei&limit=5"

# Geolocate an IP
curl https://countries.dev/ip/8.8.8.8

Choosing the right endpoint

You need... Use
One country, and you have its ISO code /alpha/{code} (most reliable — prefer this)
One country by name /name/{name} (substring match — may return several; pick the best match)
Lists filtered by region/currency/language/etc. /region/…, /currency/…, /lang/…, etc.
Countries in a population or area range /population?min=&max=, /area?min=&max=
A country's neighbours (full records) /borders/{country name} — takes a name like germany, NOT an ISO code
City search / coordinates /cities?q=… (ranked by population)
Any geographic feature (mountains, rivers…) /places?q=…&class=…
Nearest city/place to coordinates /cities/near?lat=&lng=, /places/near?lat=&lng=
ZIP/postal code → place + coordinates /postal/{alpha2}/{code}
IP → country /ip (caller), /ip/{ip}, or POST /ip for batches
Distance between two points /distance?lat1=&lng1=&lat2=&lng2= or ?from=&to= (GeoNames IDs, not names)

For the complete endpoint list, every query parameter, response schemas, and verified examples, read references/endpoints.md.

Key conventions (learned from live testing — trust these)

  1. Single-lookup endpoints return an object; search/filter endpoints return an array — even when only one item matches. /alpha/JP → object; /name/japan → [ {...} ].
  2. Use fields= aggressively. Full country records are large. Request only what you need: ?fields=name,capital,population. Use ?fields=full to get everything including altSpellings, maps, translations, and regionalBlocs (these four are omitted by default).
  3. List endpoints support sort, order (asc/desc), limit, offset for sorting and pagination.
  4. Name search is substring-based: /name/united returns every country containing "united". Don't assume the first result is the intended one — match on the name field or fall back to /alpha/{code} when you know the code.
  5. /borders takes a country name (/borders/germany works; /borders/DE and /borders/DEU return 404 "Country not found"). To get just neighbour codes, read the borders array (alpha-3 codes) from the country record instead.
  6. /distance does not accept city names or country codes — only lat1/lng1/lat2/lng2 coordinates or GeoNames IDs via from/to. To get the distance between two named cities, first resolve each via /cities?q=name to get its geonameId, then call /distance?from=ID&to=ID.
  7. URL-encode special characters: timezone lookups need the + encoded, e.g. /timezone/UTC%2B08:00.
  8. Flags: the flag field is an emoji (🇹🇼); image URLs live in flags.png / flags.svg (hosted on flagcdn.com).