Help: Migration from Region auto completion v1 API (DEPRECATED) to GeoAutoCompletion (GAC) v2 API

This page helps you to migrate from the deprecated Region auto completion v1 API to the GeoAutoCompletion (GAC) v2 API.

Major tech differences

Type v1 (DEPRECATED) v2
URI restapi/api/search/v1.0/region restapi/api/gis/v2.0/geoautocomplete/{DEU|AUT}
Query q={QUERY} i={INPUT}
    t=quarterOrTown
Response content

region

region.name

region.geoCodeId

region.amount

entity

entity.type

entity.id

entity.label

matches

matches.offset

matches.length
Media Types application/xml; application/json application/json

Additional functionalities

  • More countries: GER and AUT (AUT is new)
  • Two resources: suggestion and entity
  • More flexibility for response with entity types
  • More information (response group "matches")

Comparision of requests and responses

Region auto completion v1 API (DEPRECATED)

GET https://rest.immobilienscout24.de/restapi/api/search/v1.0/region?q=seel

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<region:regions xmlns:region="http://rest.immobilienscout24.de/schema/search/region/1.0">
    <region>
        <name>Seelze</name>
        <geoCodeId>1276009018014</geoCodeId>
        <amount>0</amount>
    </region>
    <region>
        <name>Hannover-Seelhorst</name>
        <geoCodeId>1276009017055</geoCodeId>
        <amount>0</amount>
    </region>
[...]
</region:regions>

GET https://rest.immobilienscout24.de/restapi/api/search/v1.0/region?q=seel

Accept: application/json

{
  "region.regions": [
    {
      "region": [
        {
          "name": "Seelze",
          "geoCodeId": 1276009018014,
          "amount": 0
        },
        {
          "name": "Hannover-Seelhorst",
          "geoCodeId": 1276009017055,
          "amount": 0
        },
        [...]
      ]
    }
  ]
}

GeoAutoCompletion (GAC) v2 API

GET https://rest.immobilienscout24.de/restapi/api/gis/v2.0/geoautocomplete/DEU?i=seel&t=quarterOrTown

[
  {
    "entity": {
      "type": "quarterOrTown",
      "id": "1276009018014",
      "label": "Seelze"
    },
    "matches": [
      {
        "offset": 0,
        "length": 4
      }
    ]
  },
  {
    "entity": {
      "type": "quarterOrTown",
      "id": "1276009017055",
      "label": "Hannover-Seelhorst"
    },
    "matches": [
      {
        "offset": 9,
        "length": 4
      }
    ]
  },
[...]
]