La API para
el servidor PorMiCiudad
La API está diseñada para la compartición pública
de la información acumulada en la base de datos de la Plataforma Ciudad, es
decir, para funciones de búsqueda y consulta de los reportes enviados por los
ciudadanos.
Se devuelven hasta 1000 solicitudes en cada consulta. Dichas solicitudes
se ordenan de acuerdo a la fecha de comienzo, así que para obtener todas las
solicitudes es necesario hacer varias solicitudes ajustando la fecha de
comienzo y final.
La información puede recuperarse en formato XML y JSON.
El acceso es público para esta primera versión de la API. Estamos en desarrollo de un módulo aplicativo
para que las consultas a la API anexen un token otorgado a personas registradas, ello es para prevenir solamente
casos de búsquedas excesivas o que sobrecarguen el servidor, toda vez que la información
que proporciona la API es de naturaleza pública y es accesada
también desde front-end de la plataforma a través de
las interfaces normales con el usuario.
Especificaciones de la API
|
API Endpoint |
https://pormiciudad.online/api/v2 |
|
Portal API /
Página de inicio |
https://pormiciudad.online |
|
Categoría
primaria |
Ámbito Público |
|
Categorías
secundarias |
Comunidades, Ciudades, Municipios, Localización |
|
URL de la página
de inicio de Docs |
|
|
Alcance |
API de propósito
único |
|
Específico a
Dispositivo |
No |
|
Estilo
Arquitectónico |
REST |
|
Formatos de
solicitud admitidosURI |
Query String |
|
Formatos de
respuesta compatibles |
XML, JSON |
Descubrimiento de servicio
Archivo de descubrimiento de servicio estándar
asociado con ellas para proporcionar enrutamiento entre versiones y tipos de
API.
Internacionalización y codificación
Formato de fecha/hora Todos los campos de
fecha/hora deben formatearse en un subconjunto común de ISO 8601 según la nota
w3. Se debe incluir la información de zona horaria (Z significa UTC, o un
desplazamiento HH: MM de UTC).
Ejemplos:
Codificación
UTF-8 se utilizado en todas partes.
Todo el texto devuelto por el servicio, ya sea en
XML, JSON o cualquier otro tipo de contenido basado en texto, está codificado
en UTF-8. Los encabezados HTTP y el elemento raíz van precedidos de la
declaración XML que incluya el atributo encoding="UTF-8".
Soporte de formatos
XML es un formato requerido, pero JSON se puede
proporcionar también. Los formatos de salida admitidos por el proveedor se
indican a través del campo Formatos de descubrimiento de servicio para el punto
final de API que se está utilizando. El cliente puede especificar el
formato deseado agregando el nombre del formato al recurso. Por ejemplo,
una solicitud GET a /services.xml para la salida text/xml de los recursos
y servicios, y /services/01.json
para salida application/json (RFC 4627).
Los encabezados de tipo de contenido HTTP tienen
este aspecto para cada formato:
Soporte XML
XML para la API debe ser Content-Type: text/xml. La
salida XML actualmente definida no tiene esquema y no tiene una declaración de
espacio de nombres. Para garantizar que todos los clientes puedan admitir
la salida XML, se recomienda cumplir estrictamente con la especificación y no
incluir etiquetas o espacios de nombres extranjeros.
Soporte JSON
JSON para la API debe ser Content-Type: application/json. El soporte de JSON se basa en un mapeo
programático del formato XML usando la Convención Spark. Lo
que quiere decir si tiene un archivo XML, puede generar fácilmente la versión
JSON con XSL. Esto se puede hacer usando un servidor XSLT.
Seguridad
El uso de HTTPS para los métodos es
obligatorio. No obstante que la
información de PorMiCiudad es por definición pública.
Definiciones
jurisdition_id
Permite que esta API distinga múltiples
jurisdicciones dentro de un punto final de la API, es el identificador único para las
ciudades. Se define por el nombre de dominio del sitio de la plataforma PorMiCiudad (sin www y sin el
.online o .com) como "jurisdiction_id".
Por ejemplo, jurisdiction_id=pormiciudad,
o jurisdiction_id=tlaxcala, o jurisdiction_id=ecatepec, o jurisdiction_id=coyoacan, etc. Las
implementaciones pueden ignorar este parámetro y tratarlo como un
"argumento opcional" si la implementación solo sirve a una
jurisdicción, es decir si solo comprende a una sola ciudad o municipio.
Argumentos opcionales
"Opcional" significa que la respuesta
debe ser la misma si se pasa un parámetro y está vacío o no se pasa en
absoluto. Un parámetro nulo debe tratarse como equivalente a un parámetro
no declarado en el procesamiento de la solicitud.
Atributos devueltos en cada petición
|
Atributo devuelto |
Descripción |
|
service_request_id |
Es un
único Id del servicio request creado. |
|
description |
Una descripción
completa del request o reporte que está siendo
enviado (es decir, recuperado al cliente). |
|
lat, long |
Latitud y
Longitud usando la proyección(WGS84) . |
|
media_url |
La URL a los
medios asociados con la solicitud, por ejemplo, una imagen. |
|
status |
Opciones: abierto,
cerrado |
|
requested_datetime |
La fecha
y hora en que se realizó la solicitud de servicio. Devuelto en formato w3,
por ejemplo, 2010-01-01T00: 00: 00Z |
|
updated_datetime |
La fecha
y hora en que se modificó por última vez la solicitud de servicio. Para
solicitudes con estado = cerrado, esta será la fecha en que se cerró la
solicitud. Devuelto en formato
w3, por ejemplo, 2010-01-01T00: 00: 00Z |
|
service_code |
El
identificador único para el tipo de solicitud de servicio (Categoría del
Problema a reportar) |
|
service_name |
El nombre
legible por humanos del tipo de solicitud de servicio (Categoría
del Problema a reportar) |
|
agency_sent_datetime |
La hora en
que se envió el reporte al Ayuntamiento. |
|
title |
Título de
Reporte enviado al Ayuntamiento |
|
interface_used |
Si se envió por web o por móvil. |
|
comment_count |
El número
de veces que este reporte ha sido comentado o se le han proporcionado
actualizaciones de otros usuarios. |
|
requestor_name |
Es el nombre de la persona que
envió el reporte. Solo si el solicitante permitió que el nombre que se
mostrará en el sitio. |
|
agency_responsible |
Se utiliza para listar las administraciones
que han recibido la notificación de problemas. Es también posible buscar por agency_responsible
para limitar las solicitudes a las enviados a una sola administración |
Parámetros para búsquedas
|
service_request_id |
Buscar por
ID numérico específico de un reporte. Usar esto es idéntico a preguntar por
un request individual usando el URL /requests/number.format. |
|
service_code |
Buscar por la categoría dada o la
cadena del tipo de servicio. |
|
Status |
Buscar por reportes abiertos o
cerrados (arreglados). |
|
start_date
|
Sólo regresa
reportes después de cierta fecha requerida o en la fecha y hora. El formato
es YYYY-MM-DDTHH:MM:SS+TZ:TZ. |
|
end_date |
Sólo regresa
reportes establecidos antes de la fecha y hora especificados. Tiene el mismo
formato que el star_date. |
|
agency_responsible
|
ID del cuerpo de gobierno local que
recibe los reportes. Diversos ID’s pueden ser
especificados con un caracter separador “|”. Este
ID es el que el sistema le otorgó al crear el cuerpo o departamento
responsable. |
|
interface_used |
Nombre / Identificador de la
interface usada. Puede ser Web o Móbil (smartphone). |
|
has_photo |
Buscar por entradas con o sin
fotos. Use el valor “true” para traer solo los reportes que se crearon con
imágenes, y “false” para lo contrario. |
|
max_requests |
Número máximo de peticiones a
regresar de la búsqueda. Si es más largo que el valor máximo especificado en en la llamada a Discovery, el valor provisto aquí es ignorado.
El número máximo de entradas que la Api puede regresar es 1000. |
Métodos
API
1.
INFORMACIÓN DE DESCUBRIMIENTO (Discovery)
https://pormiciudad.online/api/v2/discovery.xml?jurisdiction_id=pormiciudad
Respuesta:
<discovery>
<changeset>2019-04-08T00:00:00Z</changeset>
<contact>Send email to
contacto.pormiciudad@gmail.com.</contact>
<endpoints>
<endpoint>
<changeset>2019-04-08T00:00:00Z</changeset>
<formats>
<format>text/xml</format>
<format>application/json</format>
<format>text/html</format>
</formats>
<specification>https://plataforma.pormiciudad.online/api</specification>
<type>production</type>
<url>https://pormiciudad.online/api</url>
</endpoint>
<endpoint>
<changeset>2019-04-08T00:00:00Z</changeset>
<formats>
<format>text/xml</format>
<format>application/json</format>
<format>text/html</format>
</formats>
<specification>https://plataforma.pormiciudad.online/api</specification>
<type>test</type>
<url>https://pormiciudad.online/api</url>
</endpoint>
</endpoints>
<key_service>Use
una Api Key que puede generar en el sitio
https://pormiciudad.online/apikey/register
-en desarrollo a Julio de 20019, etapa Beta deployment</key_service>
<max_requests>1000</max_requests>
</discovery>
2. OBTENER
Lista de servicios
|
Propósito |
Proporcionar una lista de tipos de solicitud de servicio aceptables y
sus códigos de servicio asociados. Estos tipos de solicitud pueden ser exclusivos
de la ciudad o de alguna jurisdicción. |
|
URL |
https: // [punto final API] / services. [formato] |
|
Formatos |
XML (JSON disponible) |
|
Método HTTP |
GET |
|
Requiere clave API |
No |
URL de muestra para Probar
|
https://pormiciudad.online/api/v2/services.xml?jurisdiction_id=pormiciudad.online Recupera los servicios que se
presentan en la plataforma https://pormiciudad.online/api/v2/services.json?jurisdiction_id=pormiciudad&lat=19.4&long=-99.1 Recupera los servicios que se
presentan en las coordenadas latitud=19.4
y longitud=-99.1 (Centro de la
Ciudad de México). Salida en JSON. a) De click
en el link de arriba o cópielo en algún navegador. b) Si desea la salida en JSON con
formato utf-8 cambie “xml” por “json”
en la URL de arriba. |
Argumentos requeridos
|
Nombre del campo |
Descripción |
Notas y requisitos |
|
jurisdiction_id |
|
Esto solo se requiere si el punto final sirve a múltiples
jurisdicciones |
Respuesta
|
Nombre del campo |
Descripción |
Notas y requisitos |
|
services ⇊ |
|
|
|
service ↴ |
|
|
|
service_code |
El identificador
único para el tipo de solicitud de servicio. |
|
|
service_name |
El nombre legible
por humanos del tipo de solicitud de servicio. |
|
|
description |
Una breve
descripción del tipo de solicitud de servicio. |
|
|
metadata |
Determina si hay
campos de formulario adicionales para este tipo de servicio. true: Este tipo de
solicitud de servicio requiere metadatos adicionales, por lo que el cliente
deberá realizar una llamada al método de Definición de servicio (Discovery). |
Valores posibles: true, false. |
|
type |
realtime: El ID de la solicitud de servicio se devolverá inmediatamente después
de que se envíe la solicitud de servicio. |
Valores posibles: realtime, batch, blackbox. |
|
keywords |
Una lista de
etiquetas o palabras clave separadas por comas para ayudar a los usuarios a
identificar el tipo de solicitud. Esto puede proporcionar sinónimos del service_name y el grupo. |
|
|
group |
Una categoría
para agrupar este tipo de servicio. Esto proporciona una forma de
agrupar varios tipos de solicitudes de servicio en una categoría, como
"saneamiento" |
|
Posibles errores
Los números representan el código de estado HTTP devuelto para cada tipo
de error:
3. OBTENER
solicitud de servicio
|
Propósito |
Consultar el estado actual de una solicitud individual |
|
URL |
https: // [punto final de la API] /requests/ [service_request_id].
[formato] |
|
Formatos |
XML (JSON disponible) |
|
Método HTTP |
GET |
|
Requiere clave API |
No |
URL’s de muestra para Probar
|
https://pormiciudad.online/api/v2/requests/37.xml?jurisdiction_id=pormciudad.online Recuperar el reporte con ID=37 https://pormiciudad.online/api/v2/requests/1.json?jurisdiction_id=pormciudad.online Recuperar el reporte con ID=1 en
salida JSON a) De click en el link de arriba o cópielo en algún navegador. b) Si desea la
salida en JSON con formato utf-8 cambie “xml” por “json” en la URL de arriba. |
Argumentos requeridos
|
Nombre del campo |
Descripción |
Notas y requisitos |
|
jurisdiction_id |
|
Esto solo se requiere si el punto final sirve a múltiples
jurisdicciones |
|
service_request_id |
|
service_request_id se especifica en la ruta URL principal en lugar de un parámetro de
cadena de consulta agregado. |
Argumentos opcionales
Ninguno
Respuesta
|
Nombre del campo |
Descripción |
Notas y requisitos |
|
service_requests ⇊ |
|
|
|
request ↴ |
|
|
|
service_request_id |
El ID único de la
solicitud de servicio creada. |
|
|
status |
El estado actual
de la solicitud de servicio. |
Opciones: open, closed |
|
status_notes |
Explicación de
por qué el estado se cambió al estado actual o más detalles sobre el estado
actual que transmitido con el estado solo. |
No puede ser devuelto |
|
service_name |
El nombre legible
por humanos del tipo de solicitud de servicio |
|
|
service_code |
El identificador
único para el tipo de solicitud de servicio |
|
|
description |
Una descripción
completa de la solicitud o informe enviado. |
Esto puede contener saltos de línea, pero no html
o código. De lo contrario, este es un texto de forma libre limitado a 4.000
caracteres. |
|
agency_responsible |
El gobierno loical responsable de cumplir o abordar la solicitud de
servicio. En este caso solo es válido si un mismo sitio de pormiciudad contiene varios municipios. |
No puede ser devuelto |
|
service_notice |
Información sobre
la acción esperada para cumplir con la solicitud o abordar la información
reportada. |
No puede ser devuelto |
|
requested_datetime |
La fecha y hora
en que se realizó la solicitud de servicio. |
Devuelto en formato w3, por ejemplo, 2019-01-01T00: 00: 00Z |
|
updated_datetime |
La fecha y hora
en que se modificó por última vez la solicitud de servicio. Para
solicitudes con estado = cerrado, esta será la fecha en que se cerró la
solicitud. |
Devuelto en formato w3, por ejemplo, 2019-01-01T00: 00: 00Z |
|
expected_datetime |
La fecha y hora
en que se puede esperar que se cumpla la solicitud de servicio. Esto
puede basarse en un acuerdo de nivel de servicio específico del servicio. |
No puede ser devuelto |
|
address |
Dirección legible
por humanos o descripción de la ubicación. |
Debe proporcionarse desde la unidad geográfica más específica a la más
general, por ejemplo, número de dirección o cruce de calles, nombre de la
calle, barrio / distrito, ciudad / pueblo / aldea, condado, código postal. |
|
address_id |
La ID de
dirección interna utilizada por un repositorio de direcciones maestro de
jurisdicciones u otro sistema de direccionamiento. |
|
|
zipcode |
El código postal
para la ubicación de la solicitud de servicio. |
|
|
lat |
latitud usando
la proyección (WGS84) . |
|
|
long |
longitud utilizando
la proyección (WGS84) . |
|
|
media_url |
Una URL a los
medios asociados con la solicitud, por ejemplo, una imagen. |
Aún no se ha establecido una convención para analizar los medios desde
esta URL, por lo que actualmente se hará caso por caso, como lo hace
twitter.com |
Posibles errores
Los números representan el código de estado HTTP
devuelto para cada tipo de error:
4. OBTENER
solicitudes de servicio
|
Propósito |
Consultar el
estado actual de múltiples solicitudes |
|
URL |
https: // [punto final de la API] / requests. [formato] |
|
Formatos |
XML (JSON disponible) |
|
Método HTTP |
GET |
|
Requiere clave API |
No |
URL’s de muestra
para Probar
|
1 2 3 4 5 |
Recupera todos los reportes entre el 24 de enero al 24 de abril de 2019
que tengan el estatus de “abiertos” (problemas sin reparar todavía). Recupera todos los reportes con categoría de “Basura de la calle”. https://pormiciudad.online/api/v2/requests.xml?jurisdiction_id=pormiciudad&status=closed Recupera todos los reportes que tengan el estatus de
“Arreglado”. Recupera todos los reportes que tengan el estatus de
“Abierto” en las Alcaldías de Coyoacán=1 y Azcapotzalco=5 (Los ID’s de agency_responsible se
obtienen del administrador del sistema o de su publicación para fines de uso
de la API). Recupera
todos los reportes que haya enviado el usuario ciudadano de nombre “Jorge
Portillo” hasta antes del 24 de Mayo de 2019. Salida JSON. a) De click
en el link de arriba o cópielo en algún navegador. b)
Si desea la salida en JSON con formato utf-8 cambie “xml” por “json” en la URL de
arriba. |
Argumentos requeridos
|
Nombre del campo |
Descripción |
Notas y requisitos |
|
jurisdiction_id |
|
Esto solo se requiere si el punto final sirve a múltiples
jurisdicciones |
Argumentos opcionales
|
Nombre del campo |
Descripción |
Notas y requisitos |
|
service_request_id |
Para llamar a múltiples solicitudes de servicio a la vez, se pueden
declarar múltiples service_request_id; separado
por comas. |
Esto anula todos los demás argumentos. |
|
service_code |
Especifique el tipo de servicio llamando a la ID única del código_servicio. |
Esto predeterminado a todos los códigos de servicio cuando no se
declara; se puede declarar varias veces, delimitado por comas |
|
start_date |
Fecha y hora más temprana para incluir en la búsqueda. Cuando se
proporciona end_date, le permite a uno buscar
solicitudes que tienen un tiempo request_date que
coincide con un rango determinado, pero que no puede abarcar más de 90 días. |
Cuando no se especifica, el rango se predetermina a los 90 días más
recientes. Debe usar el formato w3, por ejemplo, 2010-01-01T00: 00: 00Z. |
|
end_date |
Última fecha y hora para incluir en la búsqueda. Cuando se
proporciona start_date, le permite a uno buscar
solicitudes que tienen un request_datetime que
coincide con un rango determinado, pero que no puede abarcar más de 90 días. |
Cuando no se especifica, el rango se predetermina a los 90 días más
recientes. Debe usar el formato w3, por ejemplo, 2010-01-01T00: 00: 00Z. |
|
status |
Permite buscar solicitudes que tienen un estado específico. Esto
predeterminado a todos los estados; se puede declarar varias veces,
delimitado por comas; |
Opciones: open, closed |
Respuesta
|
Nombre del campo |
Descripción |
Notas y requisitos |
|
service_requests ⇊ |
|
|
|
request ↴ |
|
|
|
service_request_id |
El ID único de la
solicitud de servicio creada. |
|
|
status |
El estado actual
de la solicitud de servicio. |
Opciones: open, closed |
|
status_notes |
Explicación de por
qué el estado se cambió al estado actual o más detalles sobre el estado
actual que transmitido con el estado solo. |
No puede ser devuelto |
|
service_name |
El nombre legible
por humanos del tipo de solicitud de servicio |
|
|
service_code |
El identificador único
para el tipo de solicitud de servicio |
|
|
description |
Una descripción
completa de la solicitud o informe enviado. |
Esto puede contener saltos de línea, pero no html
o código. De lo contrario, este es un texto de forma libre limitado a
4.000 caracteres. |
|
agency_responsible |
La agencia
responsable de cumplir o abordar la solicitud de servicio. |
No puede ser devuelto |
|
service_notice |
Información sobre
la acción esperada para cumplir con la solicitud o abordar la información
reportada. |
No puede ser devuelto |
|
requested_datetime |
La fecha y hora
en que se realizó la solicitud de servicio. |
Devuelto en formato w3, por ejemplo, 2010-01-01T00: 00: 00Z |
|
updated_datetime |
La fecha y hora
en que se modificó por última vez la solicitud de servicio. Para
solicitudes con estado = cerrado, esta será la fecha en que se cerró la
solicitud. |
Devuelto en formato w3, por ejemplo, 2010-01-01T00: 00: 00Z |
|
expected_datetime |
La fecha y hora
en que se puede esperar que se cumpla la solicitud de servicio. Esto puede
basarse en un acuerdo de nivel de servicio específico del servicio. |
No puede ser devuelto |
|
address |
Dirección legible
por humanos o descripción de la ubicación. |
Debe proporcionarse desde la unidad geográfica más específica a la más
general, por ejemplo, número de dirección o cruce de calles, nombre de la
calle, barrio / distrito, ciudad / pueblo / aldea, condado, código postal. |
|
address_id |
La ID de
dirección interna utilizada por un repositorio de direcciones maestro de
jurisdicciones u otro sistema de direccionamiento. |
|
|
zipcode |
El código postal
para la ubicación de la solicitud de servicio. |
|
|
lat |
latitud usando
la proyección (WGS84) . |
|
|
long |
longitud utilizando
la proyección (WGS84) . |
|
|
media_url |
Una URL a los
medios asociados con la solicitud, por ejemplo, una imagen. |
Aún no se ha establecido una convención para analizar los medios desde
esta URL, por lo que actualmente se hará caso por caso, como lo hace
Twitter.com |
Volumen de respuesta
Posibles errores
Los números representan el código de estado HTTP
devuelto para cada tipo de error: