{ "openapi": "3.1.0", "info": { "title": "BlurLoc API", "version": "v1", "summary": "Privacy-oriented IPv4 partial-prefix geolocation lookup", "description": "BlurLoc accepts truncated or wildcard IPv4 prefixes and returns coarse geolocation and network metadata without requiring a full IP address. Partial prefixes are preferred because they preserve privacy and support more GDPR-conscious integrations. Learn more at https://blurloc.com/" }, "externalDocs": { "description": "Learn more about BlurLoc", "url": "https://blurloc.com/" }, "servers": [ { "url": "https://blurloc.com", "description": "Production" }, { "url": "http://localhost:8080", "description": "Local development" } ], "paths": { "/lookup/{pattern}": { "get": { "operationId": "lookupLatest", "summary": "Lookup by partial IPv4 prefix", "description": "Recommended latest route. Prefer truncated input such as `44.206.` over exact IPv4 input.", "parameters": [ { "name": "pattern", "in": "path", "required": true, "description": "IPv4 prefix or exact IP. Preferred form is truncated prefix, e.g. `44.206.`", "schema": { "type": "string", "examples": [ "44.206.", "44.206.x.x", "44.206.12x.x", "44.206.123.x", "44.206.123.45" ] } }, { "name": "full", "in": "query", "required": false, "description": "Include verbose nested match data", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "strict", "in": "query", "required": false, "description": "Strict mode is ON by default. Exact IPv4 input is rejected with 400. Pass strict=0 to disable (compatibility mode). Omitting the parameter or passing strict=1 leaves strict mode enabled.", "schema": { "type": "string", "enum": [ "0", "1" ] } }, { "name": "debug", "in": "query", "required": false, "description": "Include debug metadata such as duration", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "Lookup response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupResponse" } } } }, "400": { "description": "Invalid input or strict-mode rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/lookup/{pattern}": { "get": { "operationId": "lookupV1", "summary": "Versioned lookup route", "description": "Same behavior as `/lookup/{pattern}` but pinned to v1.", "parameters": [ { "$ref": "#/components/parameters/Pattern" }, { "$ref": "#/components/parameters/Full" }, { "$ref": "#/components/parameters/Strict" }, { "$ref": "#/components/parameters/Debug" } ], "responses": { "200": { "description": "Lookup response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupResponse" } } } }, "400": { "description": "Invalid input or strict-mode rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/health": { "get": { "operationId": "health", "summary": "Health check", "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } } }, "components": { "parameters": { "Pattern": { "name": "pattern", "in": "path", "required": true, "description": "IPv4 prefix or exact IP. Preferred form is truncated prefix, e.g. `44.206.`", "schema": { "type": "string" } }, "Full": { "name": "full", "in": "query", "required": false, "description": "Include verbose nested match data", "schema": { "type": "string", "enum": [ "1" ] } }, "Strict": { "name": "strict", "in": "query", "required": false, "description": "Strict mode is ON by default. Exact IPv4 input is rejected with 400. Pass strict=0 to disable (compatibility mode). Omitting the parameter or passing strict=1 leaves strict mode enabled.", "schema": { "type": "string", "enum": [ "0", "1" ] } }, "Debug": { "name": "debug", "in": "query", "required": false, "description": "Include debug metadata such as duration", "schema": { "type": "string", "enum": [ "1" ] } } }, "schemas": { "HealthResponse": { "type": "object", "required": [ "api_version", "status", "time" ], "properties": { "api_version": { "type": "string", "example": "v1" }, "status": { "type": "string", "example": "ok" }, "time": { "type": "string", "format": "date-time" } } }, "LookupCandidate": { "type": "object", "properties": { "network": { "type": "string" }, "probability": { "type": "number" }, "overlap_ips": { "type": "integer" } }, "additionalProperties": true }, "LookupResponse": { "type": "object", "required": [ "api_version", "query", "candidate_count", "probability", "match_type" ], "properties": { "api_version": { "type": "string", "example": "v1" }, "query": { "type": "string", "example": "44.206." }, "warning": { "type": [ "string", "null" ], "example": null }, "candidate_count": { "type": "integer", "example": 1 }, "probability": { "type": "number", "example": 1 }, "match_type": { "type": "string", "enum": [ "none", "exact", "probable" ] }, "network": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "country_name": { "type": [ "string", "null" ] }, "asn": { "type": [ "integer", "number", "null" ] }, "as_org": { "type": [ "string", "null" ] }, "is_hosting_provider": { "type": [ "boolean", "null" ] }, "is_vpn": { "type": [ "boolean", "null" ] }, "selected_match": { "$ref": "#/components/schemas/LookupCandidate" }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/LookupCandidate" } }, "debug": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } } } }