GeoAutoCompletion (GAC) v2 API

The GeoAutoCompletion (GAC) provides autocompletion and suggestion for the German part of the IS24 Geohierarchy as well as for German zip codes and German streets. We also support Austria (but not with all types of search parameters as in Germany).

http://rest.immobilienscout24.de/restapi/api/gis/v2.0/geoautocomplete/{DEU|AUT}...

Note:

  • We offer two resources: suggestion and entity
  • The geo autocompletion service is currently restricted to regions in Germany (DEU) and Austria (AUT)
  • If you need to migrate from Region auto completion v1 API (DEPRECATED), here is a help page

Supported media types

  • only! JSON (Accept: application/json)

Authorization requirements

  • At least a System Key is required for this operation. Take a look into the two-legged OAuth Authentication for further details.
  • You need an additional permission for this API. If you want to use this API please fill out this form for an API Permission Request.

Suggestion Resource

Request

Path Parameters

  • country: DEU or AUT

Query Parameters

  • i - Input for matching geographical entities (mandatory)
  • - Limit the number of results. Maximum: 100 (optional)
  • - Specify which entity types should be matched. See Entity Types (optional)

Header

No special headers.

Entity Types

The region completion distinguishes "entities" (geographical objects) which should be included in the result. Use query parameter t to select which types to consider (0-n types, comma separated, case-insensitive).

t= ... Description Examples
ALL A shortcut for "country,region,city,district,quarterOrTown,postcode,street" (please note: The parameter "trainStation" is not included).  
country country Deutschland, Österreich
region The federal states according to our Geohierarchy. Bayern, Berlin; Salzburg, Steiermark
city City (according to our Geohierarchy) (1) Berlin, Brandenburg; Salzburg (Stadt); Salzburg-Umgebung
district County (according to our Geohierarchy) (1) Frankfurt (Kreis)
quarterOrTown Parts of cities or small towns/villages in counties. Rathenow, Brandenburg an der Havel-Neustadt; Salzburg-Umgebung-Koppl, Sankt Johann im Pongau-Goldegg
postcode Input has to be an integer, result is "postcode city". "10249 Berlin"; "1010 Wien“
street Results are "street, postcode city" or "street, postcode city-quarter" (depending on whether the matching city contains quarters) "Andreasstraße 10243 Berlin-Friedrichshain (Friedrichshain)"
postcodeWithQuarter "postcode city-quarter" "10249 Berlin-Friedrichshain"; "1010 Wien-1. Bezirk, Innere Stadt"
trainStation Trainstations (only in Germany). "Aschaffenburg Hbf", "S+U Alexanderplatz"
  (1) Our geohierarchy has cities and counties on the same level. The distinction between cities and counties is done in Germany by means of the suffix "(Kreis)" or "...kreis". In Austria there is no such pattern, hence all entities on this level go as cities even if they are actually not (e.g. Salzburg-Umgebung).  

 

HowTo:

   
What How Notes
settlements of all kind t=city,quarterOrTown t=city only includes cities that are urban districts; smaller towns/villages (like Rathenow) are returned for t=quarterOrTown

Response

The following section includes the HTTP status code, a short description and examples for the response body content of a successful request. Error responses as well as other simple message responses are described in detail in the common message responses.

  • Status 200 OK - The requested operation was successful.

Examples: Request and response

GET https://rest.immobilienscout24.de/restapi/api/gis/v2.0/geoautocomplete/DEU?i=10557%20Strasse%20des&t=ALL

[
  {
    "entity":{
      "type":"street",
      "id":"S1885578",
      "label":"Straße des 17. Juni 10557 Berlin-Charlottenburg (Charlottenburg)"
    },
    "matches":[
      {
        "offset":20,
        "length":5
      },
      {
        "offset":0,
        "length":6
      },
      {
        "offset":7,
        "length":3
      }
    ]
    
  },
  {
    "entity":{
      "type":"street",
      "id":"S1885685",
      "label":"Straße des 17. Juni 10557 Berlin-Tiergarten (Tiergarten)"
    },
    "matches":[
      {
        "offset":20,
        "length":5
      },
      {
        "offset":0,
        "length":6
      },
      {
        "offset":7,
        "length":3
      }
    ]
  }
]
GET http://rest.immobilienscout24.de/restapi/api/gis/v2.0/geoautocomplete/AUT?i=Salzburg&t=city
    [
       {
           "entity":
           {
               "type": "city",
               "id": "1040005001",
               "label": "Salzburg (Stadt)"
           },
           "matches":
           [
               [
                   0,
                   8
               ]
           ]
       },
       {
           "entity":
           {
               "type": "city",
               "id": "1040005003",
               "label": "Salzburg-Umgebung"
           },
           "matches":
           [
               [
                   0,
                   8
               ]
           ]
       }
    ]

Entity Resource

Request

Path Parameters

  • country: DEU or AUT
  • id: The ID of the entity. You get IDs in the result of the suggestion resource. 

Query Parameters

  • g - GeoCodingType: One of None, GeoId, Lambert, WGS84 (case sensitive!), with the following meaning:
    - None: basic information about the entity (type, id, label, address)
    - GeoId: basic information plus the GeoId (geohierarchical id) of the region it represents or belongs to
    - Lambert: basic information plus LambertEU coordinates (x,y) of the center of the entity
    - WGS84: basic information plus Wgs84 coordinates (lat,lon) of the center of the entity

Header

No special headers.

Response

The following section includes the HTTP status code, a short description and examples for the response body content of a successful request. Error responses as well as other simple message responses are described in detail in the common message responses.

  • Status 200 OK - The requested operation was successful.

Examples: Request and response

GET http://rest.immobilienscout24.de/restapi/api/gis/v2.0/geoautocomplete/DEU/entity/1276007004

{
  "type": "city",
  "id": "1276007004",
  "label": "Frankfurt am Main",
  "address": {
    "city": "Frankfurt am Main",
    "region": "Hessen"
  }
}

GET https://rest.immobilienscout24.de/restapi/api/gis/v2.0/geoautocomplete/DEU/entity/1276003001?g=GeoId

{
  "type": "city",
  "id": "1276003001",
  "label": "Berlin",
  "geoId": "1276003001",
  "address": {
    "city": "Berlin",
    "region": "Berlin"
  }
}

GET https://rest.immobilienscout24.de/restapi/api/gis/v2.0/geoautocomplete/DEU/entity/S1190910?g=Lambert

{
  "type": "street",
  "id": "S1190910",
  "label": "Insterburger Straße 76139 Karlsruhe-Waldstadt",
  "geoData": {
    "x": -112428,
    "y": 2126542
  },
  "address": {
    "street": "Insterburger Straße",
    "postcode": "76139",
    "quarter": "Waldstadt",
    "city": "Karlsruhe"
  }
}

GET https://rest.immobilienscout24.de/restapi/api/gis/v2.0/geoautocomplete/DEU/entity/S1190910?g=WGS84

{
  "type": "street",
  "id": "S1190910",
  "label": "Insterburger Straße 76139 Karlsruhe-Waldstadt",
  "geoData": {
    "lat": 49.03796,
    "lon": 8.43886
  },
  "address": {
    "street": "Insterburger Straße",
    "postcode": "76139",
    "quarter": "Waldstadt",
    "city": "Karlsruhe"
  }
}