German Streets API Documentation

GET /api/search

Search German streets, cities, and postal codes using two different methods:

Single Query Method - Filter by one field at a time
Chaining Method - Filter by multiple fields with AND/OR logic

Single Query Method

field (optional, default: "street_name")

street_name - Search in street names
city_name - Search in city names
zip_code - Search in postal codes
regional_key - Search in regional keys
borough_name - Search in borough names

Example:

/api/search?field=city_name&value=Berlin

Response: 200

{
  "success": true,
  "data": {
    "results": [
      {
        "street_name": "Hauptstraße",
        "city_name": "Berlin",
        "zip_code": "10115",
        "regional_key": "11000000",
        "borough_name": "Mitte"
      }
    ],
    "count": 1,
    "total": 1,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

operator (optional, default: "contains")

contains - Field contains the value
contains_not - Field does not contain the value
equals - Field equals the value exactly
equals_not - Field does not equal the value
starts_with - Field starts with the value
ends_with - Field ends with the value

Example:

/api/search?field=street_name&operator=starts_with&value=Haupt

Response: 200

{
  "success": true,
  "data": {
    "results": [
      {
        "street_name": "Hauptstraße",
        "city_name": "München",
        "zip_code": "80331",
        "regional_key": "09162000",
        "borough_name": null
      }
    ],
    "count": 1,
    "total": 1,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

value (required)

The search value (max 255 characters)

Example:

/api/search?field=zip_code&operator=equals&value=10115

Response: 200

{
  "success": true,
  "data": {
    "results": [
      {
        "street_name": "Unter den Linden",
        "city_name": "Berlin",
        "zip_code": "10115",
        "regional_key": "11000000",
        "borough_name": "Mitte"
      }
    ],
    "count": 1,
    "total": 1,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

limit (optional, default: 100, max: 1000)

Number of results to return

Example:

/api/search?value=straße&limit=2

Response: 200

{
  "success": true,
  "data": {
    "results": [
      {
        "street_name": "Hauptstraße",
        "city_name": "Hamburg",
        "zip_code": "20095",
        "regional_key": "02000000",
        "borough_name": null
      },
      {
        "street_name": "Bahnhofstraße",
        "city_name": "Köln",
        "zip_code": "50667",
        "regional_key": "05315000",
        "borough_name": null
      }
    ],
    "count": 2,
    "total": 15000,
    "limit": 2,
    "offset": 0,
    "has_more": true
  }
}

fields (optional)

Comma-separated list of fields to return

Example:

/api/search?value=Berlin&fields=street_name,city_name

Response: 200

{
  "success": true,
  "data": {
    "results": [
      {
        "street_name": "Berliner Straße",
        "city_name": "Frankfurt"
      }
    ],
    "count": 1,
    "total": 1,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

offset (optional, default: 0)

Number of results to skip (for pagination)

Example:

/api/search?value=straße&limit=1&offset=1

Response: 200

{
  "success": true,
  "data": {
    "results": [
      {
        "street_name": "Kirchstraße",
        "city_name": "Dresden",
        "zip_code": "01067",
        "regional_key": "14612000",
        "borough_name": "Altstadt"
      }
    ],
    "count": 1,
    "total": 15000,
    "limit": 1,
    "offset": 1,
    "has_more": true
  }
}

Chaining Method

filters (required for chaining method)

JSON array of filter objects. Each filter must have: field, operator, value

Simple Example (single filter in JSON):

/api/search?filters=[{"field":"street_name","operator":"contains","value":"Main"}]

Response: 200

{
  "success": true,
  "data": {
    "results": [
      {
        "street_name": "Mainzer Straße",
        "city_name": "Frankfurt",
        "zip_code": "60311",
        "regional_key": "06412000",
        "borough_name": null
      }
    ],
    "count": 1,
    "total": 1,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

logic (optional, default: "AND")

How to combine multiple filter conditions

AND - All conditions must match (default)
OR - Any condition can match

Multiple filters with AND logic:

/api/search?filters=[{"field":"street_name","operator":"contains","value":"Haupt"},{"field":"city_name","operator":"equals","value":"Berlin"}]&logic=AND

Response: 200

{
  "success": true,
  "data": {
    "results": [
      {
        "street_name": "Hauptstraße",
        "city_name": "Berlin",
        "zip_code": "10115",
        "regional_key": "11000000",
        "borough_name": "Mitte"
      }
    ],
    "count": 1,
    "total": 1,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

Multiple filters with OR logic:

/api/search?filters=[{"field":"city_name","operator":"equals","value":"Berlin"},{"field":"city_name","operator":"equals","value":"München"}]&logic=OR

Response: 200

{
  "success": true,
  "data": {
    "results": [
      {
        "street_name": "Unter den Linden",
        "city_name": "Berlin",
        "zip_code": "10115",
        "regional_key": "11000000",
        "borough_name": "Mitte"
      },
      {
        "street_name": "Marienplatz",
        "city_name": "München",
        "zip_code": "80331",
        "regional_key": "09162000",
        "borough_name": null
      }
    ],
    "count": 2,
    "total": 2,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

Complex example - streets in specific zip codes OR containing "Haupt":

/api/search?filters=[{"field":"zip_code","operator":"equals","value":"10115"},{"field":"street_name","operator":"contains","value":"Haupt"}]&logic=OR&fields=street_name,city_name,zip_code

Response: 200

{
  "success": true,
  "data": {
    "results": [
      {
        "street_name": "Unter den Linden",
        "city_name": "Berlin",
        "zip_code": "10115"
      },
      {
        "street_name": "Hauptstraße",
        "city_name": "Hamburg",
        "zip_code": "20095"
      }
    ],
    "count": 2,
    "total": 2,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

Available Fields and Operators

Available Fields:

street_name - Street names
city_name - City names
zip_code - Postal codes
regional_key - Regional keys
borough_name - Borough names

Available Operators:

contains - Field contains the value
contains_not - Field does not contain the value
equals - Field equals the value exactly
equals_not - Field does not equal the value
starts_with - Field starts with the value
ends_with - Field ends with the value

Error Responses

Missing value:

/api/search?field=city_name

Response: 400

{
  "success": false,
  "error": "value_required"
}

Invalid field:

/api/search?field=invalid_field&value=test

Response: 400

{
  "success": false,
  "error": "Invalid field. Allowed fields: street_name, city_name, zip_code, regional_key, borough_name"
}

Rate limit exceeded: Response: 429

{
  "success": false,
  "error": "rate_limit_exceeded"
}

Invalid JSON in filters:

/api/search?filters=[invalid json]

Response: 400

{
  "success": false,
  "error": "Invalid JSON in filters parameter"
}

Invalid logic parameter:

/api/search?filters=[{"field":"street_name","operator":"contains","value":"Main"}]&logic=INVALID

Response: 400

{
  "success": false,
  "error": "Invalid logic parameter. Allowed values: AND, OR"
}

Empty value in filter:

/api/search?filters=[{"field":"street_name","operator":"contains","value":""}]

Response: 400

{
  "success": false,
  "error": "Empty value in filter at index 0"
}

Programming Language Examples

Complete code examples for integrating the German Streets API in your applications:

JavaScript (Node.js)

Using axios for HTTP requests:

const axios = require('axios');

async function searchStreets(searchTerm) {
  try {
    const response = await axios.get('https://germanstreets.grolmes.com/api/search', {
      params: {
        field: 'street_name',
        operator: 'contains',
        value: searchTerm,
        limit: 10
      }
    });
    return response.data.data.results;
  } catch (error) {
    console.error('Search failed:', error);
  }
}

// Usage
searchStreets('Haupt').then(results => console.log(results));

Python

Using the requests library:

import requests

def search_streets(search_term, limit=10):
    url = "https://germanstreets.grolmes.com/api/search"
    params = {
        'field': 'street_name',
        'operator': 'contains', 
        'value': search_term,
        'limit': limit
    }
    
    response = requests.get(url, params=params)
    if response.status_code == 200:
        return response.json()['data']['results']
    else:
        raise Exception(f"API request failed: {response.status_code}")

# Usage
results = search_streets('Haupt')
print(results)

PHP

Using file_get_contents (or curl for more advanced usage):

<?php
function searchStreets($searchTerm, $limit = 10) {
    $url = 'https://germanstreets.grolmes.com/api/search';
    $params = http_build_query([
        'field' => 'street_name',
        'operator' => 'contains',
        'value' => $searchTerm,
        'limit' => $limit
    ]);
    
    $response = file_get_contents($url . '?' . $params);
    $data = json_decode($response, true);
    
    return $data['data']['results'] ?? [];
}

// Usage
$results = searchStreets('Haupt');
print_r($results);
?>

cURL

Command line examples for testing:

Basic search:

curl "https://germanstreets.grolmes.com/api/search?field=street_name&operator=contains&value=Haupt&limit=10"

Multi-filter search:

curl -G "https://germanstreets.grolmes.com/api/search" \ --data-urlencode 'filters=[ {"field":"city_name","operator":"equals","value":"Berlin"}, {"field":"zip_code","operator":"starts_with","value":"10"} ]' \ --data-urlencode 'logic=AND' \ --data-urlencode 'limit=20'

German Streets API Documentation

Table of Contents

GET /api/search

Single Query Method

field (optional, default: "street_name")

operator (optional, default: "contains")

value (required)

limit (optional, default: 100, max: 1000)

fields (optional)

offset (optional, default: 0)

Chaining Method

filters (required for chaining method)

logic (optional, default: "AND")

Available Fields and Operators

Available Fields:

Available Operators:

Error Responses

Programming Language Examples

JavaScript (Node.js)

Python

PHP

cURL