<aside> <img src="/icons/exclamation-mark_gray.svg" alt="/icons/exclamation-mark_gray.svg" width="40px" /> Neivo provides a comprehensive API for delivering quality environment data to real-estate platforms and individuals in the housing market. The Neivo-API is a robust and scalable RESTful API designed to provide neighborhood scoring based on geographic coordinates.

</aside>

API Reference

🎯 Overview

The Neighborhood Scoring API provides comprehensive neighborhood quality metrics for any geographic locations in Germany. Our API delivers over 30 different scoring metrics including walkability, safety, air quality, healthcare access, and climate resilience data. This documentation outlines the API’s endpoints, request/response formats, authentication requirements, error handling, and usage guidelines. It is intended for developers integrating the neivo API into their applications.

Current Version: 2.0.0

Base URL: https://neivo-api.vercel.app

Demo: https://www.standortscore.de

🔐 Authentication

Getting Your API Key

Access to the neivo API requires a valid API Key. API keys are issued upon subscription and are subject to rate limits based on the user’s plan.

All API requests require authentication using a Bearer token in the Authorization header.

Header Format

Authorization: Bearer YOUR_API_KEY

⚠️ Security Notice: Never expose your API key in client-side code or public repositories. Always use server-side requests or a backend proxy.

Rate Limit Headers

The API enforces daily and monthly request limits, which vary by subscription plan. Rate limit information is included in the response headers:

Example Headers:

X-Rate-Limit-Daily-Remaining: 23
X-Rate-Limit-Monthly-Remaining: 98  
X-Rate-Limit-Daily-Limit: 25
X-Rate-Limit-Monthly-Limit: 100
X-Rate-Limit-Reset: 2025-08-19T00:00:00

If the rate limit is exceeded, the API returns a 429 Too Many Requests error with details in the response body.

{
  "error": "Daily limit exceeded"
}

❌ Error Handling

The API uses conventional HTTP response codes and returns JSON error objects.

HTTP Status Codes

Code Meaning Possible Causes Example Trigger
200 Success Request completed successfully Valid coordinates with API key
400 Bad Request Invalid parameters or malformed request lat=999&lon=999 (coordinates out of range)
401 Unauthorized Invalid or missing API key Authorization: Bearer invalid-key-test
404 Not Found Location data unavailable for coordinates Coordinates in Antarctica: lat=-89&lon=0
405 Method Not Allowed Wrong HTTP method used Using POST on /scores endpoint
415 Unsupported Media Type Missing or incorrect Content-Type header POST request without Content-Type: application/json
422 Unprocessable Entity Valid JSON but invalid data structure Empty hexagons array: {"hexagons": []}
429 Too Many Requests Rate limit exceeded Exceeding daily/monthly API limits
500 Internal Server Error Database or server issues Supabase connection failure

Error Response Format

{
  "error": "Error description",
  "detail": "Additional error details (optional)"
}

🛠 Endpoints

1. Health Check

Endpoint: GET /health

Description: Checks the API’s operational status. This endpoint does not require authentication

Request:

{
  "status": "healthy",
  "timestamp": "2025-08-18T19:05:15.179062",
  "version": "2.0.0"
}

Response:

{
  "status": "healthy",
  "timestamp": "2025-01-01T01:01:00Z"
}

Example:

curl -X GET "<https://neivo-api.vercel.app/health>" \\
  -H "Content-Type: application/json" | jq

2. Get Neighborhood Scores

Endpoint: GET /scores

Description: Retrieves neighborhood scores for a specified latitude and longitude. The API returns associated scores, city name, and country.

Request Parameters:

Parameter Type Required Description
lat Float Yes Latitude coordinate (WGS 84, range: -90.0 to 90.0).
lon Float Yes Longitude coordinate (WGS 84, range: -180.0 to 180.0).
metrics String No Comma-separated list of specific metrics to return (e.g., safety,walkability).

Request Example:

GET /scores?lat=50.1468&lon=9.8792&metrics=walkability,healthcare_access,crime_safety_living
Authorization: Bearer YOUR_API_KEY

Response:

{
  "latitude": 50.0000,
  "longitude": 9.0000,
  "city_name": "City",
  "country": "Country",
  "scores": {
    "walkability": 66,
    "healthcare_access": 76,
    "crime_safety_living": 98,
    "air_quality": 81,
    "green_space_access": 100
  },
  "timestamp": "2025-08-01T20:00:00.000000"
}

Example

curl -X GET "<https://neivo-api.vercel.app/scores?lat=50.0000&lon=9.0000&metrics=walkability,healthcare_access,crime_safety_living>" \\
  -H "Authorization: Bearer nyqCIoBqJC" \\
  -H "Content-Type: application/json" | jq

3. Get Bulk Location Scores

Endpoint: POST /scores/bulk

Description: Retrieve scores for multiple H3 hexagon locations in a single request. Optimized for map visualizations.

Request Parameters:

Parameter Type Required Description
hexagons Array[String] Yes List of H3 hexagon IDs (maximum 100 per request).
metrics Array[String] No List of specific metrics to return (e.g., ["walkability", "crime_safety_living"]). If omitted, all available metrics are returned.

Request Example:

curl -X POST "<https://neivo-api.vercel.app/scores/bulk>" \\
  -H "Authorization: Bearer nyqCIoBqJC" \\
  -H "Content-Type: application/json" \\
  -d '{
    "hexagons": ["123456abcdefg", "123456abcdefh", "123456abcdefi"],
    "metrics": ["walkability", "healthcare_access", "air_quality"]
  }' | jq

Response:

{
  "results": [
    {
      "hexagon_id": "891f0600003ffff",
      "lat": 54.325543773976825,
      "lng": 10.209808056925771,
      "city_name": "Kiel",
      "country": "Germany", 
      "status": "success",
      "walkability": 33,
      "healthcare_access": 96,
      "crime_safety_living": 58
    }
  ],
  "metadata": {
    "total_requested": 3,
    "successful": 3,
    "failed": 0,
    "processing_time": 1.2028
  }
}