Integre la API de The Grant Map

Empiece sin clave

Inicio rápido en cinco minutos

La muestra pública devuelve una colección de una ciudad con la misma forma de registro que usa la API con licencia. Sirve para probar análisis, mapeo de campos, presentación por idioma y advertencias sin crear una cuenta ni enviar información personal.

curl --fail-with-body \
  https://www.thegrantmap.com/api/sample \
  | python3 -m json.tool

Antes de evaluar o usar la API en producción, revise también la respuesta vigente sobre la salud del conjunto, la puerta de preparación para ventas pagadas y el documento OpenAPI. Estos recursos legibles por máquina forman parte de la evaluación del comprador y no son afirmaciones de marketing. Esta guía se cotejó con esos endpoints públicos el 25 de julio de 2026; las respuestas en ejecución controlan las cifras, fechas, versiones y el estado de preparación que pueden cambiar.

Campo y Zonas Rurales es un piloto separado fuera del contrato de datos Home, por lo que sus endpoints no se incluyen en el documento OpenAPI.

Demostración sin clave

Explore la muestra pública

Cargue la muestra pública desde esta página y fíltrela localmente por tipo de proyecto o nombre del programa. El explorador nunca solicita una clave ni envía el texto del filtro al servidor. Muestra como máximo seis registros de vista previa; use el JSON sin procesar para inspeccionar la colección de evaluación devuelta completa. La muestra aplica el mismo alcance de reparaciones del hogar y la misma cuarentena de problemas conocidos que las rutas de programas con licencia, por lo que no representa todas las filas guardadas de la ciudad.

Control de acceso

Autenticación y alcance de evaluación

Los endpoints con licencia exigen una clave en el encabezado de solicitud X-Api-Key. La autenticación de la API conserva un hash unidireccional. Una copia cifrada de entrega para una emisión aprobada de una clave se conserva mientras la entrega esté pendiente o sea ambigua y se elimina cuando un evento firmado del proveedor confirma la entrega. Si la entrega sigue siendo ambigua, los reintentos pueden prolongar esa retención, por lo que aquí no se promete un plazo fijo de eliminación. Este proceso de claves no es un canal de entrega de archivos masivos. El equipo de soporte puede revocar y rotar una clave, pero no puede recuperar el texto sin cifrar después de eliminar la copia cifrada. Guarde el valor sin procesar en un administrador de secretos del servidor o en una variable de entorno local; no lo inserte en JavaScript del navegador.

echo "Pegue la clave y pulse Return (entrada oculta):"
read -s TGM_API_KEY

printf 'header = "X-Api-Key: %s"\n' "$TGM_API_KEY" | \
curl --fail-with-body --config - \
  --header "Accept: application/json" \
  "https://www.thegrantmap.com/api/programs/des-moines?type=homeowner&project=exterior"
unset TGM_API_KEY

El ejemplo de shell entrega el encabezado secreto a curl mediante la entrada estándar, de modo que la clave sin procesar no aparece en los argumentos del proceso de curl. La inspección del entorno del proceso aún puede exponer secretos locales; use el administrador de secretos de su plataforma en producción.

La tabla describe límites de ejecución, no un menú de compra autoservicio. Solo la oferta comercial anual puede usar pago autoservicio y únicamente mientras la puerta pública de lanzamiento comercial esté en verde. El acceso para organizaciones sin fines de lucro o académicas requiere revisión manual de elegibilidad y alcance. La disponibilidad del piloto asistido está en pausa hasta que se revisen el alcance y las condiciones de retención; ninguna de esas dos vías se ofrece mediante pago autoservicio.

Los límites se determinan a partir del nivel vigente de la clave en el momento de la solicitud. El acceso también puede detenerse cuando una clave vence, se revoca o no puede validarse. El servicio falla de forma cerrada durante una interrupción de la autenticación, en vez de devolver datos con licencia sin validación.

HTTP JSON

Mapa de endpoints

Evaluación y transparencia públicas

Endpoints con licencia

Ejemplos del lado del servidor

curl, Python y JavaScript

Estos ejemplos usan variables de entorno para que las credenciales no aparezcan en el control de versiones, los argumentos de procesos ni las URL. El repositorio también incluye clientes pequeños, ejecutables y sin dependencias en docs/examples/grantmap-api/.

import json
import os
from urllib.request import Request, urlopen

key = os.environ["TGM_API_KEY"]
request = Request(
    "https://www.thegrantmap.com/api/programs/des-moines?project=exterior",
    headers={"Accept": "application/json", "X-Api-Key": key},
)
with urlopen(request, timeout=20) as response:
    payload = json.load(response)

print(payload["count"])
for program in payload["programs"][:3]:
    print(program["id"], program["freshness"]["confidence"])

const key = process.env.TGM_API_KEY;
if (!key) throw new Error("TGM_API_KEY is required");

const response = await fetch(
  "https://www.thegrantmap.com/api/programs/des-moines?project=exterior",
  { headers: { Accept: "application/json", "X-Api-Key": key } },
);
const payload = await response.json();
if (!response.ok) {
  throw new Error(`${response.status}: ${payload.code ?? payload.error}`);
}

console.log(payload.count);
for (const program of payload.programs.slice(0, 3)) {
  console.log(program.id, program.freshness.confidence);
}

Comportamiento de colecciones

Contrato de filtros y paginación

Los filtros de listas de programas se combinan con AND lógico. Los valores desconocidos normalmente producen una colección vacía válida en vez de un error de validación, por lo que debe descubrir los valores de filtros a partir de los registros devueltos y distinguir un resultado vacío de una solicitud fallida.

El feed de cambios usa paginación estable por clave. limit acepta de 1 a 1,000. Lea hasMore; mientras sea verdadero, envíe el nextCursor opaco devuelto con los mismos valores de since y city. No se detenga solo porque changes esté vacío: una página puede avanzar sobre eventos sin procesar que se retuvieron de la respuesta con licencia y aun así devolver hasMore: true. Deténgase únicamente cuando hasMore sea falso. La primera página fija snapshotMaxId, por lo que las inserciones posteriores, incluidas las filas con fecha anterior, no pueden cruzar el límite del recorrido. Inicie una nueva solicitud de primera página para descubrir eventos confirmados después de esa instantánea. Las filas de cambios heredadas no incluyen un campo de alcance de reparación del hogar, por lo que debe cotejar el ID de programa de cada evento con el endpoint publicado del programa dentro del alcance antes de usarlo en un sistema posterior.

Las respuestas de programas se serializan mediante la lista permitida del esquema JSON publicado. additionalProperties es falso: los campos internos de revisión, los auxiliares de interfaz y las futuras claves del corpus no son campos de respuesta con licencia, salvo que se revise deliberadamente el contrato publicado.

Integraciones estables

Versiones, revisiones y descontinuación

El encabezado de respuesta X-API-Version identifica el contrato HTTP semántico. El contrato servido actualmente es 1.4.0, y los endpoints sin prefijo de versión corresponden al contrato 1.x. Se pueden añadir campos opcionales y endpoints nuevos en una versión menor compatible; un cambio incompatible de respuesta o comportamiento requiere una nueva ruta de versión mayor, como /api/v2, en vez de una mutación silenciosa del contrato 1.x. Lea el encabezado o info.version de OpenAPI en tiempo de ejecución, en vez de suponer que esta página siempre mostrará el valor más reciente.

X-Dataset-Revision identifica una generación efectiva servida. Su huella determinista vincula el contrato y el esquema de revisión de la API, el corpus de ciudades activas incluido en el repositorio, la evidencia actual de vigencia, las correcciones duraderas del fundador, la implementación de enriquecimiento y el alcance con licencia y la política de exclusión activos. Los cuerpos de las respuestas exitosas de colecciones, muestras, salud y feed de cambios también exponen datasetRevision; una respuesta exitosa de detalle lo lleva solo en el encabezado. Las respuestas de error lo omiten en vez de asignar una revisión a un conjunto no disponible. Guárdelo con cada importación o resultado de evaluación para que un informe de defecto pueda identificar la generación exacta que utilizó.

Ninguna operación está marcada actualmente como obsoleta. Si se introduce un reemplazo, The Grant Map lo publicará antes del retiro, dará un aviso de al menos 90 días y marcará las respuestas afectadas con los encabezados estándar Deprecation, Sunset y Link hacia el reemplazo. El documento OpenAPI es la fuente de verdad legible por máquina para el contrato y el estado de descontinuación vigentes.

En el host público canónico, /api/sample, /api/dataset/schema, /api/dataset/export-schema y /openapi.json proporcionan un ETag y aceptan If-None-Match; una coincidencia devuelve 304 sin cuerpo. La salud del conjunto y la preparación para ventas pagadas son públicas, pero no forman parte de esa lista permitida de ETag. Las respuestas con licencia permanecen deliberadamente privadas, usan no-store, varían según X-Api-Key y omiten ETag; no debilite ese límite en una caché compartida.

Evidencia, no garantías

Semántica de vigencia y cuarentena

Cada programa servido incluye un objeto anidado freshness. Las señales describen lo que The Grant Map ha comprobado; no sustituyen la confirmación con la organización administradora.

linkStatus

live, dead, bot-blocked o unchecked. Que una URL devuelva una respuesta HTTP durante la comprobación confirma solo que respondió. No confirma ningún hecho guardado.

lastChecked

Fecha registrada del último intento aplicable de comprobar el enlace. Puede estar presente cuando linkStatus es unchecked, porque una falla de conexión u otro intento inconcluso también tiene una fecha.

confidence

Etiqueta limitada de evidencia: source-verified, federal-canonical, model-identity-reviewed, link-verified, link-resolves-unverified o unverified. Lea las descripciones del esquema JSON antes de asignar estas etiquetas a la interfaz de un producto.

sourceReviewed

Indica si se ejecutó un flujo fechado de revisión de la fuente. Una revisión de identidad asistida por un modelo no equivale a una prueba literal guardada ni a la verificación del monto.

sourceReviewStale

Es verdadero cuando la última revisión válida de la fuente tiene al menos 90 días; una revisión desactualizada no puede conservar un nivel superior de confianza vigente.

Campos en inglés y español

El esquema ofrece description/description_es, maxAmountLabel/maxAmountLabel_es y deadline/deadline_es. Los nombres de programas no se traducen. Administrador, categoría, estado de los fondos, elegibilidad, tipo de proyecto, población especial, teléfono, URL, monto numérico y campos de evidencia no tienen variantes separadas en español. Un campo de idioma puede estar vacío, desactualizado o ser ambiguo. Inspeccione el esquema y cree una alternativa explícita, en vez de suponer que todos los registros están traducidos por completo.

Para cualquier decisión relacionada con una solicitud, un presupuesto o una interfaz para consumidores, muestre la URL citada del registro y una advertencia de verificación. El estado de los fondos, los plazos, los montos, la geografía y las reglas de la organización administradora pueden cambiar entre revisiones.

Falle con claridad

Errores, límites de solicitudes y reintentos

{
  "error": "API key required. Request access at https://www.thegrantmap.com/data",
  "code": "API_KEY_REQUIRED"
}

Las rutas con límites de solicitudes publican X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset para la ventana activa. Retry-After acompaña las respuestas reintentables 429 o 503 cuando el servidor puede indicar una espera. Las respuestas con licencia de ciudades y programas se marcan como privadas y no almacenables en caché, y varían según X-Api-Key. Los clientes no deben colocarlas en una caché pública compartida. Los endpoints públicos de transparencia pueden usar políticas de caché diferentes.

No existe un panel de uso aprobado ni un servicio de avisos al 85 % o al 100 %.

Uso seguro

Qué es la API y qué no es

• Es un conjunto de datos para descubrimiento e investigación. Organiza registros publicados de programas y señales de evidencia para una revisión posterior.
• No es un motor de elegibilidad. Una coincidencia de filtros no establece elegibilidad, fondos disponibles, aprobación, monto de una adjudicación ni coordinación con otro programa.
• No contiene solicitantes ni leads. Los endpoints de programas con licencia no son una fuente de perfiles de propietarios, datos de contacto de contratistas, solicitudes, información bancaria, documentos de identidad ni otra información personal de usuarios.
• No es el sistema de registro de la organización administradora. Los consumidores y el personal deben confirmar las condiciones vigentes con la organización citada antes de actuar.
• No es una licencia sin restricciones para revender datos sin procesar. Los derechos, usos permitidos, atribución, redistribución y alcance de entrega proceden del acuerdo escrito aplicable.

Los ejemplos seguros incluyen una vista de investigación para asesores, una página de recursos para propietarios, un portal de clientes de contratistas, un flujo educativo para la administración de hipotecas o el descubrimiento de asistencia antes del financiamiento de mejoras del hogar. Mantenga el descubrimiento de programas separado, tanto en las operaciones como en el análisis, de las decisiones de crédito, seguro, pago, suscripción crediticia, precio, aprobación, denegación y beneficios automatizados.

La entrega pagada de archivos e instantáneas no está disponible. Esto incluye archivos masivos. El esquema de exportación y el candidato NDJSON interno no crean una oferta de producto. No existe un portal aprobado para compradores ni un canal privado de transferencia, y no se puede prometer ningún archivo hasta que cada dominio de fuente incluido tenga una decisión revisada sobre derechos y se superen todos los controles separados de almacenamiento, autorización, constancia de entrega, revocación, retención y eliminación.

Administración de datos

Flujo de correcciones y soporte

Reporte un posible problema de un registro por Contacto y soporte o escriba a support@thegrantmap.com. Incluya el slug de la ciudad, el ID del programa, el campo en cuestión, la URL de la fuente oficial pertinente, lo que dice la fuente y la fecha en que la revisó.

Una corrección enviada es evidencia para revisar, no una edición automática. Un cambio de fuente revisado y publicado puede aparecer después en el feed de cambios. No se promete un plazo de respuesta ni de publicación.

Revisión de ingeniería del comprador

Lista de evaluación

1. Analice la muestra pública y valide registros representativos contra el esquema JSON publicado.
2. Lea las respuestas vigentes de salud y preparación; registre el alcance con licencia, la cuarentena, la salud de los enlaces y el estado de auditoría estricta que evaluó.
3. Elija de una a cinco ciudades activas representativas para una prueba limitada, incluidos los mercados y tipos de programas que importan para su caso de uso.
4. Pruebe cada filtro que planea exponer, incluidos resultados vacíos, valores guardados desconocidos y alternativas bilingües.
5. Pruebe los comportamientos 401, 403, 404, 429 y 503 sin registrar la clave sin procesar ni tratar una falla como un éxito vacío.
6. Coteje los recuentos de listas con excludedBySafetyPolicy y observe exclusionPolicyVersion para detectar cambios de política.
7. Muestre las URL citadas y el contexto de verificación en la experiencia posterior del usuario; no presente una coincidencia de descubrimiento como una decisión de elegibilidad.
8. Revise las obligaciones de seguridad, retención, caché, redistribución, atribución, frecuencia de actualización, soporte y eliminación antes del uso en producción.