Resolve or create a city from an IP address
Resolve an IPv4 or IPv6 address through the local GeoIP catalogue. Pass the end user's ip. If ip is omitted, the API uses the request's remote IP, which over MCP is the server's address rather than the person's. Reuses an existing city with the same name, subdivision and country, or persists a shared city and location record when missing. Returns the saved city ID and fields; request include=location for coordinates. This lookup can create records even though the API uses GET, so its MCP tool requires confirm: true when confirmation is enabled. Returns 404 when the GeoIP data has no city-level location.
Request
- Base URL: https://api.purplegrain.com/api/v1
- URL: https://api.purplegrain.com/api/v1/cities/ip
- Auth: none declared
Query parameters
The end user's IPv4 or IPv6 address. Omit only when the request itself comes from that person; over MCP the remote address is the server's.
Comma-separated snake_case relationship paths to embed (JSON:API included array, or inlined for application/json). Never embedded by default; unknown paths ignored; max 10 paths. Allowed paths: location.
Response
Successful. When the include query parameter is used, the response may contain an included array (JSON:API) or inlined related resources (application/json).
Example response
{
"data": {
"type": "city"
}
}Changes
No recorded changes to this operation across all 2 revisions of this API.