{"openapi":"3.1.0","info":{"title":"QuoAPI – Address & Geocoding API","version":"1.3.0","description":"Canonical QuoAPI public API contract. Provider details and internal routes are intentionally excluded."},"servers":[{"url":"https://api.quoapi.com"}],"tags":[{"name":"address-api","description":"Validate and normalize addresses with forward and reverse geocoding."}],"paths":{"/v1/address/validate":{"post":{"operationId":"address_validate","summary":"Validate address","description":"Validate and normalize a postal address.","tags":["address-api"],"security":[{"BearerAuth":["address.validate"]}],"x-quoapi-capability":"address.validate","x-quoapi-contract-version":"1.3.0:address.validate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"line1":{"type":"string","x-quoapi-widget":"text","title":"Line1","default":"Unter den Linden 1"},"postal_code":{"type":"string","x-quoapi-widget":"text","title":"Postal Code","default":"10117"},"city":{"type":"string","x-quoapi-widget":"text","title":"City","default":"Berlin"},"country":{"type":"string","x-quoapi-widget":"country","title":"Country","default":"DE","x-quoapi-format":"iso-3166-1-alpha-2"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","x-quoapi-widget":"currency","x-quoapi-hidden":true,"description":"Optional ISO 4217 commercial context."}},"additionalProperties":false,"required":["country"]},"example":{"line1":"Unter den Linden 1","postal_code":"10117","city":"Berlin","country":"DE"}}}},"responses":{"200":{"description":"Canonical response","content":{"application/json":{"schema":{"type":"object","required":["data","request_id"],"properties":{"data":{"type":"object","additionalProperties":true,"description":"Canonical QuoAPI response data for this capability."},"request_id":{"type":"string"}}}}}},"4XX":{"description":"Canonical client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"5XX":{"description":"Canonical service error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/address/autocomplete":{"post":{"operationId":"address_autocomplete","summary":"Address autocomplete","description":"Return structured address suggestions.","tags":["address-api"],"security":[{"BearerAuth":["address.autocomplete"]}],"x-quoapi-capability":"address.autocomplete","x-quoapi-contract-version":"1.3.0:address.autocomplete","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","x-quoapi-widget":"text","title":"Query","default":"Unter den Linden 1"},"country":{"type":"string","pattern":"^[A-Z]{2}$","x-quoapi-widget":"country","x-quoapi-hidden":true,"description":"Optional ISO 3166-1 alpha-2 routing context."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","x-quoapi-widget":"currency","x-quoapi-hidden":true,"description":"Optional ISO 4217 commercial context."}},"additionalProperties":false,"required":["query"]},"example":{"query":"Unter den Linden 1"}}}},"responses":{"200":{"description":"Canonical response","content":{"application/json":{"schema":{"type":"object","required":["data","request_id"],"properties":{"data":{"type":"object","additionalProperties":true,"description":"Canonical QuoAPI response data for this capability."},"request_id":{"type":"string"}}}}}},"4XX":{"description":"Canonical client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"5XX":{"description":"Canonical service error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/geocode/forward":{"post":{"operationId":"geocode_forward","summary":"Forward geocode","description":"Convert an address to coordinates.","tags":["address-api"],"security":[{"BearerAuth":["geocode.forward"]}],"x-quoapi-capability":"geocode.forward","x-quoapi-contract-version":"1.3.0:geocode.forward","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","x-quoapi-widget":"text","title":"Query","default":"Unter den Linden 1, Berlin"},"country":{"type":"string","pattern":"^[A-Z]{2}$","x-quoapi-widget":"country","x-quoapi-hidden":true,"description":"Optional ISO 3166-1 alpha-2 routing context."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","x-quoapi-widget":"currency","x-quoapi-hidden":true,"description":"Optional ISO 4217 commercial context."}},"additionalProperties":false,"required":["query"]},"example":{"query":"Unter den Linden 1, Berlin"}}}},"responses":{"200":{"description":"Canonical response","content":{"application/json":{"schema":{"type":"object","required":["data","request_id"],"properties":{"data":{"type":"object","additionalProperties":true,"description":"Canonical QuoAPI response data for this capability."},"request_id":{"type":"string"}}}}}},"4XX":{"description":"Canonical client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"5XX":{"description":"Canonical service error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/geocode/reverse":{"post":{"operationId":"geocode_reverse","summary":"Reverse geocode","description":"Convert coordinates to an address.","tags":["address-api"],"security":[{"BearerAuth":["geocode.reverse"]}],"x-quoapi-capability":"geocode.reverse","x-quoapi-contract-version":"1.3.0:geocode.reverse","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"latitude":{"type":"number","x-quoapi-widget":"number","title":"Latitude","default":"52.517"},"longitude":{"type":"number","x-quoapi-widget":"number","title":"Longitude","default":"13.3889"},"country":{"type":"string","pattern":"^[A-Z]{2}$","x-quoapi-widget":"country","x-quoapi-hidden":true,"description":"Optional ISO 3166-1 alpha-2 routing context."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","x-quoapi-widget":"currency","x-quoapi-hidden":true,"description":"Optional ISO 4217 commercial context."}},"additionalProperties":false,"required":["latitude","longitude"]},"example":{"latitude":"52.517","longitude":"13.3889"}}}},"responses":{"200":{"description":"Canonical response","content":{"application/json":{"schema":{"type":"object","required":["data","request_id"],"properties":{"data":{"type":"object","additionalProperties":true,"description":"Canonical QuoAPI response data for this capability."},"request_id":{"type":"string"}}}}}},"4XX":{"description":"Canonical client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"5XX":{"description":"Canonical service error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"QuoAPI API key"}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","details"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}}