Búsqueda de direcciones para tu aplicación.
De lo que escribe una persona a un lugar que tu producto puede usar: nombre, dirección, latitud, longitud y contexto geográfico en JSON.
Crea tu API keycurl "https://maps-api.nexode.app/v1/search?q=Miraflores&countrycodes=pe&limit=5" \ -H "X-API-Key: TU_API_KEY"
Permiso de la clave: search. Cada petición admitida consume una unidad del plan.
Qué devuelve una búsqueda
Mapora consulta Photon con datos de OpenStreetMap y normaliza los resultados para que puedas utilizarlos en formularios, entregas o selección de ubicaciones. Cada resultado incluye nombre, dirección, coordenadas, fuente y atribución. Según la información disponible, también puede incluir calle, número, distrito, ciudad, región, código postal y país. Esos campos dependen de la cobertura del proveedor; una coincidencia no equivale a verificar físicamente una dirección.
Cómo orientar los resultados
El parámetro q contiene el texto de búsqueda y requiere al menos dos caracteres. countrycodes permite limitar los resultados con códigos de país de dos letras, como pe para Perú. Puedes enviar lat y lng para priorizar una zona, o bbox para acotar el área de búsqueda. limit admite de 1 a 20 resultados. El endpoint devuelve una lista de candidatos; deja que la persona confirme el lugar antes de guardarlo.
Búsqueda mientras se escribe
Usa GET /v1/autocomplete o el componente MaporaAddressSearch para mostrar sugerencias sin obligarte a mostrar un mapa. El componente consulta desde tres caracteres, espera 350 ms y cancela resultados anteriores. Cada petición admitida consume una unidad, también desde caché; cancelar un fetch no garantiza que no haya sido admitido. Invalida la selección anterior cuando la persona edite el texto.
País, ciudad y área de búsqueda
countrycodes=PE restringe a Perú; puedes enviar hasta diez países separados por comas. Para buscar por componentes separados usa GET /v1/geocode con street, housenumber, city, district, state, county o postcode. La búsqueda libre y el autocompletado también admiten city, district y state como filtros administrativos por nombre. lat/lng prioriza cercanía y bbox acota un rectángulo minLng,minLat,maxLng,maxLat. Perú cuenta además con un índice propio de calles que devuelve referencias de vía cuando el número no está registrado, sin afirmar una coincidencia con la casa. El campo city de geocode forma parte de la consulta y no garantiza un límite administrativo.
Del resultado al mapa
Guarda el nombre elegido junto con su latitud y longitud y los componentes de dirección disponibles. Mostrar un mapa es opcional: los endpoints devuelven JSON. Puedes consultar una referencia con GET /v1/reverse, generar un mapa con POST /v1/maps o calcular rutas por calles en América con POST /v1/routes y tiempos por pares con POST /v1/matrix. Mapora no es Google Places y no certifica domicilios.
Autenticación, cuotas y errores
Envía la clave en X-API-Key o Authorization: Bearer. HTTP 401 indica una clave ausente o inválida; 403, falta de permiso o cuenta suspendida; 429, cuota o velocidad excedida. Consulta las cabeceras de cuota y respeta Retry-After. El panel muestra tu plan y consumo real.