Find an object

Basic principles

This web service uses an object’s geographic coordinates to retrieve information contained in the fields of the object in a Geoconcept map. The call to the web service requires as parameters the layer name, the structure of the map and of the field(s) to interrogate.

Find an object example

{
        "url":"https://api.geoconcept.com/EU/GCW/geoconcept-web/api/lbs/find/findObject/v2.json",
        "method":"POST",
    "body":
    {
       "srs":"epsg:4326",
       "geometries":"1,-5.617883,36.027288",
       "layerName":"STANDARD",
       "targets":[
          {
             "className":"Administrative unit",
             "subClassName":"Order1",
             "fields":"Name;Government code"
          },
          {
             "className":"Administrative unit",
             "subClassName":"Order2",
             "fields":"Name;Government code"
          },
          {
             "className":"Administrative unit",
             "subClassName":"Order8",
             "fields":"Name;Government code"
          }
       ]
    }
}

Parameters / properties

Input

parameter	description	optional
srs	projection (EPSG code such as epsg:4326 or wgs84)	no
geometries	Coordinates to find (series of Id,X,Y triplets separated by the ";" character)	no
layerName	Name of the layer to use	no
targets	Properties of searched objects	no

Targets

parameter	description	optional
targetID	Identifier	yes
className	Name of the Class	no
subclassName	Name of the Subclass	no
fields	Name of the fields separated by the ";" character	no
maxDistance	Maximum search radius (in meters)	yes
maxCandidates	Maximum number of candidates to return	yes

Output

parameter	type	min/max	description
id	string	0/1	Objects identifier
targets	array (Targets Infos)	0/unlimited	Objects

Target Infos (findTargetResult)

parameter	type	min/max	description
targetID	string	0/1	Identifier
objects array (Objects Info)	string	0/unlimited	Object descriptions

Objects Info

parameter	type	min/max	description
distance	integer	1/1	Distance in meters betwen the origin point and the found object -1 if the calculated distance is not available
wktGeometry	string	0/1	Object geometry

Possible returns

Case of a response that is found (findObjectsResults/status est OK)

{
  "message": null,
  "status": "OK",
  "results": [
    {
      "id": "1",
      "targets": [
        {
          "objects": [
            {
              "distance": 0,
              "fields": [
                "Andalucía",
                "01"
              ]
            }
          ]
        },
        {
          "objects": [
            {
              "distance": 0,
              "fields": [
                "Cádiz",
                "11"
              ]
            }
          ]
        },
        {
          "objects": [
            {
              "distance": 0,
              "fields": [
                "Tarifa",
                "11035"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Absence of an object on the position searched (status is OK)

{
  "message": null,
  "status": "OK",
  "results": [
    {
      "id": "1",
      "targets": [
        {
          "objects": []
        },
        {
          "objects": []
        },
        {
          "objects": []
        }
      ]
    }
  ]
}

Faulty projection / srs (status is ERROR)

An error append : (500) Internal Server Error
CoordinateTransformEngineException: Coordinate tranformation failed

Case, absence of an argument for geometries (status est ERROR)

An error append : (500) Internal Server Error
IllegalArgumentException: Geometry has too few fields : String[][{1,-45.617883}]

Case of a layer that is not found (status is ERROR)

An error append : (500) Internal Server Error
WebServiceException: Layer name 'Europ' does not exist

Case of a Class that is not found (status est ERROR)

An error append : (500) Internal Server Error
WebServiceException: Error in finding objects
failed to execute text request
failed to execute gcis request (text response)
failed to execute gcis request
exception occured while servicing request
Failed to service request
com.geoconcept.gc.GcException: native returned exception (code=1)
native returned exception
[FindObject-88304] unknown type 'Administrative uni'

Case of a Subclass that is not found (status est ERROR)

An error append : (500) Internal Server Error
WebServiceException: Error in finding objects
failed to execute text request
failed to execute gcis request (text response)
failed to execute gcis request
exception occured while servicing request
Failed to service request
com.geoconcept.gc.GcException: native returned exception (code=1)
native returned exception
[FindObject-88305] unknown subtype 'Order'

Case of a field not found (serviceResult/status est ERROR)

An error append : (500) Internal Server Error
WebServiceException: Error in finding objects
failed to execute text request
failed to execute gcis request (text response)
failed to execute gcis request
exception occured while servicing request
Failed to service request
com.geoconcept.gc.GcException: native returned exception (code=1)
native returned exception
[FindObject-88300] unknown field 'Government cod'

FAQ

1. What are the layerName availables?
2. What are the className, subClassName and fieds availables?
3. Is it possible to use other topological relationships between objects?
4. Is it possible to pass several geometries when calling a Web Service?

1.

What are the layerName availables?

For the moment, only the STANDARD layer is available.

2.

What are the className, subClassName and fieds availables?

See list below:

className	subClassName	fields
Administrative unit	Country	Name, Country code (ISO), Country code (EBU)
	Order8	Name, Government code
	Order2	Name, Government code
	Order1	Name, Government code
Postal boundaries	Postal areas	Name, Postcode, Country code (ISO), Admin1, Admin2, Admin3, Admin4, Admin5

	Warning
	The coverage of the Administrative unit and Postal boundaries is not homogeneous, it depends on the administrative levels of each country and of the avaibility of the data providers. Please contact us for specific coverage.

Sample on fews coutries

Country	Postal Boundary	Postal items	Order1	Order1 items	Order1 example	Order2	Order2 items	Order2 example	Order8	Order8 items	Order8 example
France	Yes	60 53	Yes	14	Ile de France (11)	Yes	97	Tarn (81)	Yes	36 560	Castres (81065)
Belgium	Yes	1 147	Yes	3	Bruxelles (4)	Yes	11	Anvers (01)	Yes	589	Saint-Gilles (00083)
Germany	Yes	8 203	Yes	16	Schleswig-Holstein (01)	Yes	401	Hamburg (02000)	Yes	11 130	Flensburg (01001000)
Spain	Yes	10 806	Yes	19	Aragón (02)	Yes	52	Alicante (03)	Yes	8 126	Cerdido (15025)
Italy	Yes	4 605	Yes	20	Sardegna (20)	Yes	107	Torino (001)	Yes	7 991	Trinitapoli (110010)
Ireland	Yes	23	Yes	26	Dublin (26)	N/A			N/A
Luxembourg	Yes	3 982	Yes	3	Luxembourg (1)	Yes	12	Esch-sur-Alzette (01)	Yes	106	Kiischpelt (00871)
Netherlands	Yes	4 043	Yes	12	Groningen (20)	N/A			Yes	388	Molenwaard (6452)
Portugal	Yes	532	Yes	29	Aveiro (1)	N/A			Yes	308	Horta (1)
United Kingdom	Yes	9 671	Yes	2	Guernsey (1)	N/A			N/A
Switzerland	Yes	3 184	Yes	26	Jura (26)	Yes	148	Genève (25)	Yes	2 240	Zurich (0261)
Greece	Yes	1 083	Yes	13	Ανατολική Μακεδονία Θράκη (11)	Yes	51	Χανιά (434)	Yes	1 034	Γαύδος : (9462)
Brazil	Yes	18 263	Yes	5	Norte (1)	Yes	27	Oropeza (101)	Yes	327	Sucre (10101)
…

3.

Is it possible to use other topological relationships between objects?

No, for the moment, only the Intersect relationship is available.

4.

Is it possible to pass several geometries when calling a Web Service?

Yes, it will suffice to specify more triplets separated by the ";" character

{
  "srs": "epsg:4326",
  "geometries": "1,-5.617883,36.027288;2,25.825734,71.109870",
  "layerName": "Europe",
  "targets": [
    {
      "className": "Administrative unit",
      "subClassName": "Order1",
      "fields": "Name;Government code"
    },
    {
      "className": "Administrative unit",
      "subClassName": "Order2",
      "fields": "Name;Government code"
    },
    {
      "className": "Administrative unit",
      "subClassName": "Order8",
      "fields": "Name;Government code"
    }
  ]
}

Return:

{
  "message": null,
  "status": "OK",
  "results": [
    {
      "id": "1",
      "targets": [
        {
          "objects": [
            {
              "distance": 0,
              "fields": [
                "Andalucía",
                "01"
              ]
            }
          ]
        },
        {
          "objects": [
            {
              "distance": 0,
              "fields": [
                "Cádiz",
                "11"
              ]
            }
          ]
        },
        {
          "objects": [
            {
              "distance": 0,
              "fields": [
                "Tarifa",
                "11035"
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "2",
      "targets": [
        {
          "objects": [
            {
              "distance": 0,
              "fields": [
                "Finnmark",
                "20"
              ]
            }
          ]
        },
        {
          "objects": []
        },
        {
          "objects": [
            {
              "distance": 0,
              "fields": [
                "Nordkapp",
                "2019"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Prev	Up	Next
	Home

Geoptimization API - Geoptimization REST API

Basic principles

Find an object example

Parameters / properties

Possible returns

FAQ