{"openapi":"3.1.0","info":{"title":"PlacaHoy — API pública de restricción vehicular","version":"1.1.0","description":"¿Mi placa circula hoy? Pico y placa (Colombia, Ecuador), Hoy No Circula (México), restricción vehicular (Chile, Costa Rica, Bolivia) y rodízio (Brasil). Reglas tomadas de fuentes oficiales con fecha de verificación. Solo lectura, sin llave, con límite por IP. ATRIBUCIÓN OBLIGATORIA: «Fuente: PlacaHoy.com» con enlace a la URL de la ciudad. Si `status` es `unconfirmed`, indica que no hay confirmación: nunca lo presentes como «puede circular».","contact":{"name":"PlacaHoy","url":"https://placahoy.com"},"license":{"name":"Uso con atribución","url":"https://placahoy.com/terminos/"}},"servers":[{"url":"https://placahoy.com"}],"paths":{"/api/v1/public/hoy":{"get":{"operationId":"hoy","summary":"¿Qué placas no circulan hoy en una ciudad?","parameters":[{"name":"pais","in":"query","required":true,"description":"País ISO 3166-1 alfa-2 (CO, MX, EC, CL, CR, BO, BR).","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"ciudad","in":"query","required":true,"description":"Slug de la ciudad (`bogota`, `cdmx`, `sao-paulo`) o ruta (`co/bogota`). Un país o un departamento/estado que solo agrupa ciudades responde 404: la medida depende de cada ciudad (lista en `/api/v1/public/ciudades`).","schema":{"type":"string"}},{"name":"vehiculo","in":"query","required":false,"description":"Tipo de vehículo base: particulares (defecto), motos, taxis, carga…","schema":{"type":"string","default":"particulares"}},{"name":"fecha","in":"query","required":false,"description":"Fecha local AAAA-MM-DD (defecto: hoy en la ciudad).","schema":{"type":"string","format":"date"}},{"name":"holograma","in":"query","required":false,"description":"Solo México (Hoy No Circula): holograma de verificación (`00`, `0`, `1`, `2`, `foraneo`, `exento`, `sin-holograma`). Sin él, la respuesta del día es la del holograma por defecto (1), declarado en `assumed`, con el resto en `conditional`; con `digito` no se supone: si el dígito depende del holograma, responde `unconfirmed` con el desglose.","schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta del día","content":{"application/json":{"schema":{"type":"object","required":["attribution","data","meta"],"properties":{"attribution":{"type":"object","description":"OBLIGATORIO mostrar `text` con enlace a `url` al citar la respuesta.","properties":{"text":{"type":"string","const":"Fuente: PlacaHoy.com"},"url":{"type":"string","format":"uri"},"required":{"type":"boolean"},"license":{"type":"string"}}},"data":{"type":"object","properties":{"country":{"type":"string"},"city":{"type":"object","properties":{"path":{"type":"string"},"name":{"type":"string"}}},"measure":{"type":"string","description":"Nombre local de la medida (pico y placa, Hoy No Circula, rodízio…)."},"vehicle":{"type":"string"},"date":{"type":"string","format":"date"},"status":{"type":"string","enum":["restricted","free","no_measure","suspended","unconfirmed","exempt"],"description":"`unconfirmed` = no pudimos confirmar: NO significa que se pueda circular."},"digit":{"type":"integer"},"digitStatus":{"type":"string","enum":["restricted","free","no_measure","suspended","unconfirmed","exempt"]},"restrictedDigits":{"type":"array","description":"Dígitos restringidos del día para la consulta. Si falta un calificador (holograma), es la respuesta para el valor por defecto que declara `assumed`; el resultado de cada otro valor está en `conditional` (kind=qualifier): léelo antes de concluir.","items":{"type":["integer","string"]}},"windows":{"type":"array","items":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","description":"HH:MM local."},"to":{"type":"string","description":"HH:MM local (≤ from o `endsNextDay` = termina al día siguiente)."},"endsNextDay":{"type":"boolean"},"digits":{"description":"Dígitos a los que aplica ESTA franja (si falta, los del día).","oneOf":[{"type":"array","items":{"type":["integer","string"]}},{"type":"string","const":"all"}]}}}},"conditional":{"type":"array","description":"Resultado por calificador que la consulta no trajo (holograma del Hoy No Circula: `kind=qualifier`), por subárea (`subarea`) o por variante (`variant`). Un holograma `exempt` NO tiene restricción aunque `restrictedDigits` traiga todos los dígitos.","items":{"type":"object","required":["kind","label","status"],"properties":{"kind":{"type":"string","enum":["subarea","variant","qualifier"]},"label":{"type":"string"},"question":{"type":"string"},"qualifier":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}},"jurisdiction":{"type":"string"},"status":{"type":"string","enum":["restricted","free","no_measure","suspended","unconfirmed","exempt"]},"restrictedDigits":{"type":"array","items":{"type":["integer","string"]}},"windows":{"type":"array","items":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","description":"HH:MM local."},"to":{"type":"string","description":"HH:MM local (≤ from o `endsNextDay` = termina al día siguiente)."},"endsNextDay":{"type":"boolean"},"digits":{"description":"Dígitos a los que aplica ESTA franja (si falta, los del día).","oneOf":[{"type":"array","items":{"type":["integer","string"]}},{"type":"string","const":"all"}]}}}}}}},"assumed":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Calificador SUPUESTO porque la consulta no lo trajo (p. ej. `{\"hologram\":\"1\"}`): `status`, `restrictedDigits`, `windows` y `summary` responden para él; null si no hubo supuesto."},"carryOver":{"type":["object","null"],"description":"Franja del día anterior que sigue vigente pasada la medianoche (hasta `until`, hora local).","properties":{"fromDate":{"type":"string","format":"date"},"until":{"type":"string"},"restrictedDigits":{"type":"array","items":{"type":["integer","string"]}},"digitRestricted":{"type":["boolean","null"]}}},"holiday":{"type":["string","null"],"description":"Festivo del día, si lo hay."},"override":{"type":["object","null"],"description":"Excepción oficial del día (contingencia, día sin carro, decreto…).","properties":{"kind":{"type":"string"},"reason":{"type":"string"}}},"summary":{"type":"string","description":"Una frase en español (portugués en Brasil). «Hoy/Mañana/El {fecha}» según la fecha pedida."},"confidence":{"type":"string","enum":["high","medium","low"]},"officialSources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"lastVerified":{"type":["string","null"],"format":"date"},"validUntil":{"type":"string","format":"date-time"},"url":{"type":"string","format":"uri"},"disclaimer":{"type":"string"}}},"meta":{"type":"object","properties":{"engine":{"type":"string"},"snapshotHash":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"dataAgeSeconds":{"type":"integer"}}}}}}}},"404":{"description":"Ciudad desconocida, país sin datos, o país/departamento que agrupa ciudades"},"429":{"description":"Límite de tasa"}}}},"/api/v1/public/placa":{"get":{"operationId":"placa","summary":"¿Mi placa (último dígito) circula en una fecha?","parameters":[{"name":"pais","in":"query","required":true,"description":"País ISO 3166-1 alfa-2 (CO, MX, EC, CL, CR, BO, BR).","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"ciudad","in":"query","required":true,"description":"Slug de la ciudad (`bogota`, `cdmx`, `sao-paulo`) o ruta (`co/bogota`). Un país o un departamento/estado que solo agrupa ciudades responde 404: la medida depende de cada ciudad (lista en `/api/v1/public/ciudades`).","schema":{"type":"string"}},{"name":"vehiculo","in":"query","required":false,"description":"Tipo de vehículo base: particulares (defecto), motos, taxis, carga…","schema":{"type":"string","default":"particulares"}},{"name":"fecha","in":"query","required":false,"description":"Fecha local AAAA-MM-DD (defecto: hoy en la ciudad).","schema":{"type":"string","format":"date"}},{"name":"holograma","in":"query","required":false,"description":"Solo México (Hoy No Circula): holograma de verificación (`00`, `0`, `1`, `2`, `foraneo`, `exento`, `sin-holograma`). Sin él, la respuesta del día es la del holograma por defecto (1), declarado en `assumed`, con el resto en `conditional`; con `digito` no se supone: si el dígito depende del holograma, responde `unconfirmed` con el desglose.","schema":{"type":"string"}},{"name":"digito","in":"query","required":true,"description":"Último dígito de la placa (0–9). Nunca envíes la placa completa.","schema":{"type":"integer","minimum":0,"maximum":9}}],"responses":{"200":{"description":"Estado del dígito","content":{"application/json":{"schema":{"type":"object","required":["attribution","data","meta"],"properties":{"attribution":{"type":"object","description":"OBLIGATORIO mostrar `text` con enlace a `url` al citar la respuesta.","properties":{"text":{"type":"string","const":"Fuente: PlacaHoy.com"},"url":{"type":"string","format":"uri"},"required":{"type":"boolean"},"license":{"type":"string"}}},"data":{"type":"object","properties":{"country":{"type":"string"},"city":{"type":"object","properties":{"path":{"type":"string"},"name":{"type":"string"}}},"measure":{"type":"string","description":"Nombre local de la medida (pico y placa, Hoy No Circula, rodízio…)."},"vehicle":{"type":"string"},"date":{"type":"string","format":"date"},"status":{"type":"string","enum":["restricted","free","no_measure","suspended","unconfirmed","exempt"],"description":"`unconfirmed` = no pudimos confirmar: NO significa que se pueda circular."},"digit":{"type":"integer"},"digitStatus":{"type":"string","enum":["restricted","free","no_measure","suspended","unconfirmed","exempt"]},"restrictedDigits":{"type":"array","description":"Dígitos restringidos del día para la consulta. Si falta un calificador (holograma), es la respuesta para el valor por defecto que declara `assumed`; el resultado de cada otro valor está en `conditional` (kind=qualifier): léelo antes de concluir.","items":{"type":["integer","string"]}},"windows":{"type":"array","items":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","description":"HH:MM local."},"to":{"type":"string","description":"HH:MM local (≤ from o `endsNextDay` = termina al día siguiente)."},"endsNextDay":{"type":"boolean"},"digits":{"description":"Dígitos a los que aplica ESTA franja (si falta, los del día).","oneOf":[{"type":"array","items":{"type":["integer","string"]}},{"type":"string","const":"all"}]}}}},"conditional":{"type":"array","description":"Resultado por calificador que la consulta no trajo (holograma del Hoy No Circula: `kind=qualifier`), por subárea (`subarea`) o por variante (`variant`). Un holograma `exempt` NO tiene restricción aunque `restrictedDigits` traiga todos los dígitos.","items":{"type":"object","required":["kind","label","status"],"properties":{"kind":{"type":"string","enum":["subarea","variant","qualifier"]},"label":{"type":"string"},"question":{"type":"string"},"qualifier":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}},"jurisdiction":{"type":"string"},"status":{"type":"string","enum":["restricted","free","no_measure","suspended","unconfirmed","exempt"]},"restrictedDigits":{"type":"array","items":{"type":["integer","string"]}},"windows":{"type":"array","items":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","description":"HH:MM local."},"to":{"type":"string","description":"HH:MM local (≤ from o `endsNextDay` = termina al día siguiente)."},"endsNextDay":{"type":"boolean"},"digits":{"description":"Dígitos a los que aplica ESTA franja (si falta, los del día).","oneOf":[{"type":"array","items":{"type":["integer","string"]}},{"type":"string","const":"all"}]}}}}}}},"assumed":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Calificador SUPUESTO porque la consulta no lo trajo (p. ej. `{\"hologram\":\"1\"}`): `status`, `restrictedDigits`, `windows` y `summary` responden para él; null si no hubo supuesto."},"carryOver":{"type":["object","null"],"description":"Franja del día anterior que sigue vigente pasada la medianoche (hasta `until`, hora local).","properties":{"fromDate":{"type":"string","format":"date"},"until":{"type":"string"},"restrictedDigits":{"type":"array","items":{"type":["integer","string"]}},"digitRestricted":{"type":["boolean","null"]}}},"holiday":{"type":["string","null"],"description":"Festivo del día, si lo hay."},"override":{"type":["object","null"],"description":"Excepción oficial del día (contingencia, día sin carro, decreto…).","properties":{"kind":{"type":"string"},"reason":{"type":"string"}}},"summary":{"type":"string","description":"Una frase en español (portugués en Brasil). «Hoy/Mañana/El {fecha}» según la fecha pedida."},"confidence":{"type":"string","enum":["high","medium","low"]},"officialSources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"lastVerified":{"type":["string","null"],"format":"date"},"validUntil":{"type":"string","format":"date-time"},"url":{"type":"string","format":"uri"},"disclaimer":{"type":"string"}}},"meta":{"type":"object","properties":{"engine":{"type":"string"},"snapshotHash":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"dataAgeSeconds":{"type":"integer"}}}}}}}},"400":{"description":"Parámetros inválidos"},"404":{"description":"Ciudad o país sin datos"}}}},"/api/v1/public/verificacion":{"get":{"operationId":"verificacion","summary":"¿Cuándo le toca verificar a mi vehículo? (verificación vehicular de México por engomado y semestre)","parameters":[{"name":"pais","in":"query","required":true,"description":"País ISO (hoy: MX).","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"ciudad","in":"query","required":true,"description":"Estado o ciudad de MATRÍCULA (`cdmx`, `estado-de-mexico` o uno de sus municipios).","schema":{"type":"string"}},{"name":"vehiculo","in":"query","required":false,"description":"Tipo de vehículo base: particulares (defecto), motos, taxis, carga…","schema":{"type":"string","default":"particulares"}},{"name":"fecha","in":"query","required":false,"description":"Fecha local AAAA-MM-DD (defecto: hoy en la ciudad).","schema":{"type":"string","format":"date"}},{"name":"digito","in":"query","required":false,"description":"Último dígito NUMÉRICO de la placa (0–9); sin él responde qué engomados verifican ese día. Nunca envíes la placa completa.","schema":{"type":"integer","minimum":0,"maximum":9}},{"name":"holograma","in":"query","required":false,"description":"Holograma vigente (`00`, `0`, `1`, `2`, `exento`): los exentos no verifican en ese semestre.","schema":{"type":"string"}}],"responses":{"200":{"description":"Calendario de verificación de la fecha","content":{"application/json":{"schema":{"type":"object","required":["attribution","data","meta"],"properties":{"attribution":{"type":"object","description":"OBLIGATORIO mostrar `text` con enlace a `url` al citar la respuesta.","properties":{"text":{"type":"string","const":"Fuente: PlacaHoy.com"},"url":{"type":"string","format":"uri"},"required":{"type":"boolean"},"license":{"type":"string"}}},"data":{"type":"object","properties":{"country":{"type":"string"},"city":{"type":"object","properties":{"path":{"type":"string"},"name":{"type":"string"}}},"measure":{"type":["string","null"]},"vehicle":{"type":"string"},"date":{"type":"string","format":"date"},"dayStatus":{"type":"string","enum":["active","exempt","suspended","no_measure","unconfirmed"],"description":"`active` = hay un calendario publicado que cubre la fecha."},"digit":{"type":"integer"},"status":{"type":"string","enum":["due","grace","closed","upcoming","exempt","suspended","no_measure","unconfirmed"],"description":"`due` = su periodo está abierto · `grace` = prórroga general · `closed` = ya pasó este semestre · `upcoming` = aún no empieza · `unconfirmed` = no hay calendario confirmado (NO significa «no te toca»)."},"group":{"type":["object","null"],"description":"Engomado (color) de la terminación.","properties":{"key":{"type":"string"},"label":{"type":"string"},"color":{"type":["string","null"]},"digits":{"type":"array","items":{"type":"integer"}}}},"current":{"type":["object","null"]},"previous":{"type":["object","null"]},"next":{"type":["object","null"],"description":"Próximo periodo publicado (null si el calendario siguiente aún no se publica)."},"dueToday":{"type":"array","description":"Engomados que pueden verificar ese día.","items":{"type":"object"}},"exemptIf":{"type":["object","null"],"additionalProperties":{"type":"array","items":{"type":"string"}}},"summary":{"type":"string"},"confidence":{"type":"string","enum":["high","medium","low"]},"officialSources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"url":{"type":"string","format":"uri"},"disclaimer":{"type":"string"}}},"meta":{"type":"object","properties":{"engine":{"type":"string"},"snapshotHash":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"dataAgeSeconds":{"type":"integer"}}}}}}}},"404":{"description":"Ciudad o estado desconocido, o país sin datos"},"429":{"description":"Límite de tasa"}}}},"/api/v1/public/ciudades":{"get":{"operationId":"ciudades","summary":"Ciudades con medida y la URL de su página","parameters":[{"name":"pais","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Búsqueda por nombre (insensible a tildes).","schema":{"type":"string"}}],"responses":{"200":{"description":"Ciudades"}}}}}}