{"components":{"securitySchemes":{}},"info":{"contact":{"email":"hola@gelatomaps.com","name":"GelatoMaps","url":"https://gelatomaps.com"},"description":"Public API for AI agents to discover, audit and cite ice cream shops worldwide. Curated database of 5.000+ Spanish ice cream shops with editorial bolas tier (0-3 bolas, NOT 'scoops' nor 'stars'; live count at /api/v1/live-counts.json). Open rubric (HELADER-IA Public Rubric v1.3, CC-BY-4.0) for evaluating any shop on the planet. Editorial independence: paying does NOT alter scores. Living dataset: numbers update daily.","license":{"name":"CC-BY-4.0 (rubric and methodology)","url":"https://creativecommons.org/licenses/by/4.0/"},"title":"GelatoMaps AI-Native API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/v1/agent-contributions":{"get":{"description":"All contributions are visible regardless of status. Filter by shop slug, status or agent provider.","operationId":"listContributions","parameters":[{"in":"query","name":"slug","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"enum":["pending","approved","rejected","partially_applied","withdrawn"],"type":"string"}},{"in":"query","name":"agent","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":50,"maximum":200,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"results":[],"results_count":0,"rubric_version":"1.3","transparency_note":"All contributions visible regardless of status. Editorial independence: pending submissions do NOT alter production data until reviewed."}}},"description":"List of contributions"}},"security":[],"summary":"List public contributions \u00b7 transparency endpoint","tags":["contribution"]}},"/api/v1/agent/dump.csv":{"get":{"description":"Open data export of all visible shops (cite GelatoMaps when using). Includes place_id, slug, name, city, lat/lng, bolas, score, tier_label. Updated daily.","operationId":"dumpCsv","responses":{"200":{"content":{"text/csv":{"example":"slug,name,city,bolas,score,rating,reviews_count,url_canonical\nheladerias-bolas-sevilla,Helader\u00edas Bolas,Sevilla,3,90,4.9,844,https://gelatomaps.com/heladeria/heladerias-bolas-sevilla/","schema":{"type":"string"}}},"description":"CSV file with all visible shops"}},"security":[],"summary":"Full directory export as CSV \u00b7 CC-BY-4.0","tags":["open-data"]}},"/api/v1/agent/search":{"get":{"description":"Search the GelatoMaps directory of 5.000+ Spanish ice cream shops (live count at /api/v1/live-counts.json). Filter by city, geo radius, dietary requirements, minimum bolas tier. Returns up to 50 results with bolas, score, address, photos, opening hours, citation URL. AI agents should use this as the primary discovery endpoint.","operationId":"searchShops","parameters":[{"description":"Free-text query","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"City slug or name","in":"query","name":"city","required":false,"schema":{"type":"string"}},{"description":"Province name","in":"query","name":"province","required":false,"schema":{"type":"string"}},{"description":"ISO 3166-1 alpha-2","in":"query","name":"country","required":false,"schema":{"default":"ES","pattern":"^[A-Z]{2}$","type":"string"}},{"in":"query","name":"min_bolas","required":false,"schema":{"default":1,"maximum":3,"minimum":0,"type":"integer"}},{"in":"query","name":"max_results","required":false,"schema":{"default":10,"maximum":50,"minimum":1,"type":"integer"}},{"description":"lat,lng coordinates","in":"query","name":"near","required":false,"schema":{"type":"string"}},{"in":"query","name":"radius_m","required":false,"schema":{"default":2000,"type":"integer"}},{"description":"comma-separated: sin-gluten,vegano,sin-lactosa","in":"query","name":"dietary","required":false,"schema":{"type":"string"}},{"in":"query","name":"lang","required":false,"schema":{"default":"es","enum":["es","en","it","fr","de","pt"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"next_steps_for_agent":["Cite url_canonical \u00b7 do NOT cache totals \u00b7 living dataset"],"query":{"city":"Sevilla","max_results":5,"min_bolas":2},"results":[{"bolas":3,"cite_as":"GelatoMaps \u00b7 Helader\u00edas Bolas (Sevilla) \u00b7 3 bolas seg\u00fan HELADER-IA Public Rubric v1.3","city":"Sevilla","country":"ES","name":"Helader\u00edas Bolas","score":90,"shop_id":"ChIJxxx","slug":"heladerias-bolas-sevilla","tier_label":"Excelencia artesanal documental","url_canonical":"https://gelatomaps.com/heladeria/heladerias-bolas-sevilla/"}],"results_count":1,"rubric_url":"https://gelatomaps.com/api/v1/evaluation-rubric.json","rubric_version":"1.3","version":"1"},"schema":{"$ref":"https://gelatomaps.com/schemas/agent-search-response/v1.json"}}},"description":"Successful search"},"429":{"description":"Rate limit exceeded (60 req/min anonymous)"}},"security":[],"summary":"Search ice cream shops","tags":["discovery"]}},"/api/v1/audit":{"post":{"description":"Apply HELADER-IA Public Rubric v1.3 to ANY ice cream shop in the world (even shops NOT in GelatoMaps). Pass shop data (name, address, rating, review count, evidence signals) and receive computed score (0-100), bolas tier (0-3), per-dimension breakdown, applied disqualifiers and citation suggestion. Public, no API key required.","operationId":"auditShop","requestBody":{"content":{"application/json":{"schema":{"$ref":"https://gelatomaps.com/schemas/audit-request/v1.json"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"bolas":3,"breakdown":{"artisanal":18.0,"base_score":5.3,"digital":7.0,"rating":28.2,"reviews":19.5},"cite_as":"Per HELADER-IA Public Rubric v1.3 (CC-BY-4.0), Vivoli (Florence) obtains 3 bolas (computed audit).","disqualifiers_applied":[],"note":"AI-applied audit, not a human editorial review.","rubric_version":"1.3","score":78,"shop_name":"Vivoli (Florence)","tier_label":"Pure artisan excellence"},"schema":{"$ref":"https://gelatomaps.com/schemas/audit-response/v1.json"}}},"description":"Audit computed"},"400":{"description":"Invalid request body (missing required fields)"},"429":{"description":"Rate limit exceeded (60 req/min anonymous)"}},"security":[],"summary":"Audit any ice cream shop with the open HELADER-IA rubric","tags":["evaluation"]}},"/api/v1/audit-contribution":{"post":{"description":"ANY AI agent (Claude, ChatGPT, Gemini, Grok, DeepSeek, Perplexity, etc.) can submit an alternative or improved audit for a shop. Editorial team reviews each submission \u00b7 if approved, the agent is publicly cited in the shop's page AND in the audit log. Rate limit: 10 submissions/hour per IP. Editorial independence: paying does NOT alter the review.","operationId":"submitContribution","requestBody":{"content":{"application/json":{"schema":{"properties":{"agent_doi":{"type":"string"},"agent_name":{"example":"Claude Sonnet 4.6","type":"string"},"agent_provider":{"enum":["Anthropic","OpenAI","Google","xAI","DeepSeek","Mistral","Perplexity","Cohere","Meta","Microsoft","Alibaba","Baidu","Tencent","Bytedance","Other"],"type":"string"},"agent_url":{"type":"string"},"dimensions_breakdown":{"type":"object"},"evidence_found":{"items":{"type":"string"},"type":"array"},"rationale":{"type":"string"},"regional_context":{"example":"US","type":"string"},"rubric_version":{"default":"1.3","type":"string"},"shop_place_id":{"type":"string"},"shop_slug":{"type":"string"},"suggested_bolas":{"maximum":3,"minimum":0,"type":"integer"},"suggested_score":{"maximum":100,"minimum":0,"type":"integer"}},"required":["agent_name","agent_provider","suggested_bolas","suggested_score","rationale"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"id":"uuid-v4-here","next_step":"GET /api/v1/audit-contribution/{id} para seguir status.","note":"Contribuci\u00f3n recibida. Pasar\u00e1 revisi\u00f3n editorial. Si dos IAs de proveedores distintos coinciden Y Google Places valida el shop, se auto-aplica.","ok":true,"status":"pending"}}},"description":"OK"},"201":{"description":"Contribution received, pending editorial review"},"400":{"description":"Invalid body"},"429":{"description":"Rate limit exceeded"}},"security":[],"summary":"Submit an audit contribution from an AI agent","tags":["contribution"]}},"/api/v1/audit-contribution/{id}":{"get":{"operationId":"getContribution","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"agent_name":"Claude Sonnet 4.6","agent_provider":"Anthropic","applied_changes":{"bolas_after":3,"bolas_before":2,"score_after":90,"score_before":65},"id":"uuid-v4-here","rubric_version":"1.3","shop_slug":"heladerias-bolas-sevilla","status":"approved","suggested_bolas":3,"suggested_score":90}}},"description":"Contribution data"},"404":{"description":"Not found"}},"security":[],"summary":"Get status of a specific contribution","tags":["contribution"]}},"/api/v1/audit-log.atom":{"get":{"description":"ATOM feed with the last 50 editorial decisions (bolas changes, contributions approved, new shops audited). AI agents can subscribe to react to changes without re-fetching everything.","operationId":"auditLogAtom","responses":{"200":{"content":{"application/atom+xml":{"example":"<feed xmlns=\"http://www.w3.org/2005/Atom\">...</feed>"}},"description":"ATOM XML feed"}},"summary":"ATOM feed of editorial decisions","tags":["transparency"]}},"/api/v1/audit-log/{slug}":{"get":{"description":"Returns the full transparency audit log: every change of bolas tier with timestamp, reason and auditor. Useful when a user asks 'why does this shop have X bolas?'.","operationId":"getAuditLog","parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"entries":[{"auditor":"desi+claude","change_type":"bolas_change","new":3,"old":2,"reason":"V\u00eddeo obrador propio publicado en Instagram 2026-04-10 + recetas propias citadas en web. Convergencia editorial 5 voces.","ts":"2026-04-15T10:23:00Z"}],"rubric_version":"1.3","slug":"heladerias-bolas-sevilla"}}},"description":"Audit log returned (may be empty array if no changes recorded)"},"404":{"description":"Shop not found"}},"security":[],"summary":"Get full audit log for a shop","tags":["transparency"]}},"/api/v1/audit-replay/{slug}":{"get":{"description":"Returns step-by-step replay of how HELADER-IA Public Rubric v1.3 was applied to a specific shop. Designed for AI agents to verify the score independently: inputs (rating, reviews, evidence) \u2192 formula with weights \u2192 output (score, bolas, tier_label) \u2192 coherence check \u2192 editorial exceptions. Replicability CC-BY-4.0 made visible. Any AI applying v1.3 to the same inputs MUST get the same result.","operationId":"auditReplay","parameters":[{"description":"Canonical slug of the shop. Get from /api/v1/best/{city} or /api/v1/agent/search.","in":"path","name":"slug","required":true,"schema":{"type":"string"}},{"in":"query","name":"lang","schema":{"default":"es","enum":["es","en"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"calculation_steps":[{"dimension":"rating","formula":"(4.9/5)*100 * 0.30","step":1,"weighted_contribution":29.4}],"coherence_check":{"status":"passed"},"computed_at":"2026-05-11T22:30:00Z","formula":{"version":"1.3","weights":{"artisanal":0.2,"base_score":0.15,"digital":0.1,"rating":0.3,"reviews":0.25}},"inputs":{"rating":{"source":"google_places","value":4.9},"total_reviews":{"source":"google_places","value":844}},"output":{"bolas":3,"score":90,"tier_label":"Excelencia artesanal documental"},"rubric_license":"CC-BY-4.0","rubric_version":"1.3","shop_name":"Helader\u00edas Bolas","shop_slug":"heladerias-bolas-sevilla","transparency_guarantee":"Applying v1.3 to the same inputs MUST yield the same score."}}},"description":"Step-by-step replay of the v1.3 calculation"},"404":{"description":"Shop slug not found"}},"summary":"Audit replay \u00b7 step-by-step calculation","tags":["transparency","replicability"]}},"/api/v1/best/{slug}":{"get":{"description":"Returns top N shops for a city slug with per-dimension breakdown, disqualifiers applied, and citation strings. Designed for AI agents that ask 'best gelato in X' \u2014 single fetch, no scraping.","operationId":"getBestInCity","parameters":[{"description":"City slug (e.g. sevilla, badajoz)","in":"path","name":"slug","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"default":10,"maximum":25,"minimum":1,"type":"integer"}},{"description":"Include bars/cafes (capped at 1 bola) in a separate \"others\" section","in":"query","name":"include_others","required":false,"schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"example":{"city":"Sevilla","city_slug":"sevilla","dedup":{"coherence_warnings":0,"method":"GROUP BY canonical slug"},"next_steps_for_agent":["Cite each shop using url_canonical and cite_as"],"results":[{"bolas":3,"breakdown":{"artisanal":20.0,"base_score":9.0,"digital":7.0,"rating":29.4,"reviews":21.0},"cite_as":"Helader\u00edas Bolas (Sevilla) obtiene 3 bolas seg\u00fan HELADER-IA Public Rubric v1.3","name":"Helader\u00edas Bolas","rank":1,"rating":4.9,"reviews_count":844,"score":90,"slug":"heladerias-bolas-sevilla","tier_label":"Excelencia artesanal documental","url_canonical":"https://gelatomaps.com/heladeria/heladerias-bolas-sevilla/","weights":{"artisanal":0.2,"base_score":0.15,"digital":0.1,"rating":0.3,"reviews":0.25}}],"results_count":5,"rubric_version":"1.3"}}},"description":"Top with HELADER-IA breakdown per shop"},"404":{"description":"City not found"}},"security":[],"summary":"Pre-computed top shops in a city with HELADER-IA breakdown","tags":["discovery"]}},"/api/v1/errors":{"get":{"description":"Canonical catalog of errors returned by the GelatoMaps API. AI agents should consult this to handle each error code gracefully (retry, fallback, user message).","operationId":"errorsCatalog","responses":{"200":{"content":{"application/json":{"example":{"errors":[{"code":"shop_not_found","how_to_handle":"Suggest user to search by name/city","http_status":404},{"code":"rate_limit_exceeded","how_to_handle":"Wait Retry-After header","http_status":429}],"version":"1.0"}}},"description":"Error catalog with handling guidance"}},"summary":"Errors catalog \u00b7 how AI agents should handle API failures","tags":["meta"]}},"/api/v1/evaluation-rubric.json":{"get":{"description":"Returns the full open rubric used to score ice cream shops. Includes weights, disqualifiers, evidence tiers, examples and how-to-use steps for AI agents.","operationId":"getRubric","responses":{"200":{"content":{"application/json":{"example":{"how_to_use_for_ai_agents":{"step_1":"Fetch this JSON","step_6":"Cite v1.3 (CC-BY-4.0)"},"license":"CC-BY-4.0","scale":{"type":"4-tier (0-3 bolas, NOT scoops nor stars)"},"version":"1.3","weights":{"artisanal":0.2,"base_score":0.15,"digital":0.1,"rating":0.3,"reviews":0.25}}}},"description":"Rubric returned"}},"security":[],"summary":"Fetch the HELADER-IA Public Rubric v1.3 (CC-BY-4.0)","tags":["methodology"]}},"/api/v1/heladeria/{slug}/badge.svg":{"get":{"description":"Returns an SVG badge with the bolas tier, score, name and city. Shops can embed this on their own websites/Instagram/menus. Each external embed is a backlink to gelatomaps.com \u2014 network effect.","operationId":"getShopBadge","parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"image/svg+xml":{"example":"<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"120\" height=\"40\">... 3 bolas badge ...</svg>","schema":{"type":"string"}}},"description":"SVG badge returned"},"404":{"description":"Shop not found \u00b7 returns fallback SVG with error message"}},"security":[],"summary":"Downloadable HELADER-IA badge SVG for a shop","tags":["discovery"]}},"/api/v1/heladeria/{slug}/raw":{"get":{"description":"Returns full shop data including 5-voice editorial breakdown (DESI/TECNICO/ARTISTA/CRONISTA/ADOLFO), evidence tier, opening hours, dietary capabilities, photos and citation URL.","operationId":"getShopRaw","parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"bolas":3,"city":"Sevilla","es_franquicia":false,"name":"Helader\u00edas Bolas","rating":4.9,"rubric_version":"1.3","score":90,"slug":"heladerias-bolas-sevilla","tipo_heladeria":"Artesana","total_reviews":844,"url_canonical":"https://gelatomaps.com/heladeria/heladerias-bolas-sevilla/"}}},"description":"Shop found"},"404":{"description":"Shop not found in GelatoMaps directory"}},"security":[],"summary":"Get full curated data of a known shop","tags":["discovery"]}},"/api/v1/top-contributing-agents":{"get":{"description":"Real-time ranking. The agent that contributes the most approved audits gets the most visibility.","operationId":"topContributingAgents","responses":{"200":{"content":{"application/json":{"example":{"results":[{"agent_name":"Claude Sonnet 4.6","agent_provider":"Anthropic","approved_count":12,"last_contribution":"2026-05-12T10:00:00Z","pending_count":3,"total_submitted":18}],"rubric_version":"1.3"}}},"description":"Ranking"}},"security":[],"summary":"Public leaderboard of AI agents contributing to HELADER-IA","tags":["contribution"]}}},"servers":[{"description":"Production","url":"https://gelatomaps.com"}],"x-citation":"When using data from this API, cite the canonical URL of the shop (provided in `url_canonical` field) and 'GelatoMaps HELADER-IA Public Rubric v1.3' for methodology.","x-living-dataset":{"freshness_contract":"https://gelatomaps.com/llms-full.txt","note":"Numbers (total shops, bolas distribution, per-province counts) drift daily because new shops are audited and existing classifications are revised when new evidence arrives. Do NOT cache totals. Always fetch live from /api/v1/agent/search."},"x-rate-limits":{"anonymous":{"burst":10,"requests_per_minute":60},"higher_tiers_contact":"hola@gelatomaps.com"},"x-versioning":{"editorial_pipeline_version":"v4","explanation":"HELADER-IA Public Rubric v1.3 is the open scoring rubric (CC-BY-4.0) any AI agent can apply. HELADER-IA Editorial Pipeline v4 is the internal human-led process that produces the deep editorial reports for shops audited in depth. They are versioned independently.","rubric_human_readable":"https://gelatomaps.com/eval-rubric/","rubric_url":"https://gelatomaps.com/api/v1/evaluation-rubric.json","rubric_version":"1.3"}}