Gisgraphy user guide

importer.geonames.dir

importer.openstreetmap.dir

importer.geoname.zipcode.dir

importer.geonames.enabled

importer.openstreetmap.enabled

importerConfig.openstreetmap.fill.isin.field

importer.geonames.downloadURL

importer.geonames.zipcode.downloadURL

importer.openstreetmap.downloadURL

importer.geonamesfilesToDownload

importer.openstreetmapfilesToDownload

importer.retrieveFiles

fulltextSearchUrl

importerConfig.wrongNumberOfFieldsThrows

importerConfig.missingRequiredFieldThrows

importerConfig.acceptRegExString

importerConfig.tryToDetectAdmIfNotFound

importerConfig.syncAdmCodesWithLinkedAdmOnes

• If importerConfig.syncAdmCodesWithLinkedAdmOnes is set to 'true' then the admXcodes and admXnames of the features will be the same as the linked Adm One (in our example : if importerConfig.tryToDetectAdmIfNotFoundis set to 'true' the adm1Code will be 'A1' and the Adm2Code will be 'B2' that's to say the same as the Adm ones)
• If importerConfig.syncAdmCodesWithLinkedAdmOnes is set to 'false', the admXcodes and admXnames of the features will be the same as the CSV file (in our example : if importerConfig.tryToDetectAdmIfNotFound is set to 'true', the adm1Code will be 'A3' and the Adm2Code will be 'B2' And the Linked Adm will be null)

importerConfig.admXExtracterStrategyIfAlreadyExists

• skip : extraction will be skiped, and the existing file will be used
• backup : The already existing file will be backup (with the date and the current time), a new file will be extracted and used
• reprocess : the file will be replace by the new one

importerConfig.adm1FileName

importerConfig.adm2FileName

importerConfig.adm3FileName

importerConfig.adm4FileName

importerConfig.languageFileName

importerConfig.countriesInfosFileName

importerConfig.alternateNamesFileName

importerConfig.alternateNameFeaturesFileName

importerConfig.alternateNameAdm1FileName

importerConfig.alternateNameAdm2FileName

importerConfig.alternateNameCountryFileName

importerConfig.importGisFeatureEmbededAlternateNames

fulltextsearch.maxConnectionsPerHost

fulltextsearch.maxTotalConnections

geolocsearch.defaultGeolocSearchPlaceType

addressParser.url

useAddressParserWhenGeocoding

searchForExactMatchWhenGeocoding

addressParser.class

spellchecker.enabled

spellchecker.activeByDefault=true

spellchecker.spellcheckerDictionaryName

spellchecker.collateResults

googleMapAPIKey

googleanalytics.uacctcode

Geocoding service

Description

Output formats and languages

• XML
• Json
• Php
• Ruby
• Python
• YAML

Parameters

• The address (required) : can be a postal address, a street, a city, a postal code, a country, or a combination.
  Examples :
  • 101 Avenue des Champs-Elysées 75008 Paris
  • Champs elysees paris
  • Champs elysees
  • paris


• The country (required) : The country where the Place/address is. it is used to determine the postal address format and to improve performance. it will probably be optionnal in next version to ease the usability. The value must be the ISO 3166 Alpha 2 code of the country
  Examples :
  • US
  • FR
  • DE


• The postal : whether the given address is a postal address. default to false. In other words, if the address follow the specifications or if it is a well formed address as it was writen on an envelop. this parameter will enable the parsing of the address by the address parser before geocoding, this way, the relevance will be better because we will know the meaning of each word.
  Examples :
  • true
  • false
  • on


• The callback method name (optional), use to wrap the content into a (alphanumeric) javascript method. operate only for script output formats (json, PHP, Ruby, Python)
  Examples :
  • executeCallback :(will output "executeCallback(RESULT_FEED);" then if you evaluate this string the method will be called implicitly)


• The indentation (optional) : indents the results. Default to false. Possible values are true|false (or "on" when used with the rest service. If you use a checkbox in a web form, to indent the results, the value will be "on" or "off", so for a simple use : the value of indent, for can be "true" or "on".



Actually, only XML can be indented. It is not a bug : Indent JSON is possible but decrease performance.


• the apikey (optional) : the apikey to use if you use premium webservices this parameter is useless for local installation

Web service

Output fields description

Java API

IGeocodingService geocodingService = new GeocodingService();
	String rawAddress = "101 Avenue des Champs-Elysées 75008 Paris";
	AddressQuery query =new AddressQuery("101 Avenue des Champs-Elysées 75008 Paris", "FR");
	AddressResultsDto results =geocodingService.geocode(query);
	/* or 
	Address address=new Address();
	address.setCity("Paris");
	address.setZipCode("75008");
	address.setHouseNumber("101");
	address.setStreetType("Avenue")
	address.setStreetName("des Champs-Elysées");
	AddressResultsDto result = geocodingService.geocode(address,"FR");
	*/
	System.out.println("Query tooks "+result.getQTime()+" ms and"+
		" return "+result.getNumFound()+" result(s)");
	for (Address address : results.getResult()){
		System.out.println("housenumber : "+address.getHouseNumber());
		System.out.println("streetType : "+address.getStreetType());
		System.out.println("streetname : "+address.getStreetName());
		System.out.println("PObox : "+address.getPOBox());
		System.out.println("lat : "+address.getlat());
		System.out.println("long : "+address.getLng());
		System.out.println("city : "+address.getCity());
		System.out.println("district : "+address.getDistrict());
		System.out.println("state : "+address.getState());
		//see all fields description above...
		
	}

Adress Parser

Reverse geocoding / street service

Description

• Specify GPS position
• Give the begining or a part of the name of the street (useful for autocompletion)
• Limit search to a specific type (e.g : Pedestrian, highway, residential, ... 25 type availables)
• Limit search to a specified radius
• Limit search to one way streets
• Paginate the results
• Tells if you want the output to be indented (currently, apply only for XML, not json for performance reasons. may change in next version)

• To search for streets by entire name use the fulltext search (you can also specify GPS coordinate, and change the 'allwords required' option to esae the search).
• To do auto completion use the street webservice
• To do auto suggestion use SOLR directly (see this article in french, or use google to translate in english, i will soon add some code in the developper zone)

Output formats and languages

• XML
• Json
• Php
• Ruby
• Python
• Georss
• ATOM
• YAML

Parameters

• The latitude (north-south) for the location point to search around. The value is a float, between -90 and +90. It use GPS coordinates. could be optional but need to be valid if specified
  Examples :
  • -4.2
  • +4,2


• The longitude (east-West) for the location point to search around. The value is a float between -180 and +180. It use GPS coordinates. could be optional but need to be valid if specified
  Examples :
  • 3.6
  • 3,6


• A part of the name of the street (optional) or the name of the street : limit the search to the street that starts/contains with the specified name (WITHOUT STREET NUMBER). You could put the name and the type of the street. Example : 'Boulevard Paul'.the search is case insensitive.


The search mode is deprecated in V3.0 The fulltext mode has been removed in gisgraphy v3.0 (default is always contains) and is replaced by the fulltext search with placetype="street". The results and accuracy is really better but you can not specify oneway or streettype parameter parameter or get the distance anymore. if you really need this features, please send a mail IMPORTANT TIPS : If you need to do a fulltext search and you don't care about distance, oneway or streettype, use the fulltext search engine with placetype=street. you will get best accuracy and performance



• The radius (optional) : distance from the location point in meters we'd like to search around. The value is a number > 0 if it is not specify or incorrect : The default value will be used (10 km).
  Examples :
  • 50000


• oneway : whether the street should be a oneWay street (optional) : limit the search to the street that are one way street


• Start pagination index (optional) : The first pagination index. Numbered from 1. If the number is < 1 or not specified, it will be set to the default value : 1.


• End pagination Index (optional) : The last pagination index. if < 1 or not specified, it will be set to startindex + 50.


• The callback method name (optional), use to wrap the content into a method name, must be alphanumeric and operate only for script outputformat (json,php,ruby,python)
  Examples :
  • executeCallback :(will output "executeCallback(RESULT_FEED);" then if you evaluate this string the method will be called implicitly)


• The output format (optional) : The formats available are :
  
  • XML (Default) : Example
  • JSON : Example
  • Python
  • Ruby
  • PHP
  • ATOM : Example
  • GEORSS : Example
  • YAML



• Distance field : Wether (or not) we want the distance field to be output. This option is usefull to improve the performances if we don't care about the distance (e.g : we search for name). Of course, the results won't be sorted by distance. If you use a checkbox in a form to indent the results, the value will be "on" or "off", so to simplify the use : the value for the web service can be "true" or "on".



• The indentation (optional) : indents the results. Default to false. Possible values are true|false. If you use a checkbox in a web form to indent the results, the value will be "on" or "off", so for a simple use : the value of indent, for the web service can be "true" or "on".


Actually, only XML can be indented. It is not a bug : Indent JSON is possible but decrease performance. If it is a critical need you can see an example of how indent json in source code of streetSearchEngine.




• the apikey (optional) : the apikey to use if you use premium webservices this parameter is useless for local installation

Web service

Output fields description

Java API

			Point point = GeolocHelper.createPoint(LONGITUDE, LATITUDE);
			Pagination pagination = paginate().from(STARTINDEX).to(ENDINDEX);
			Output output = Output.withFormat(OUTPUTFORMAT)
								  .WithIndentation();
			StreetSearchQuery query = new StreetSearchQuery(point,RADIUS,
					pagination,output,STREETTYPE,
					ONEWAY,NAME);
			String results = streetSearchEngine.executeQueryToString(query);

			Point point = GeolocHelper.createPoint(-3.5F, 45F);
			Pagination pagination = paginate().from(1).to(10);
			Output output = Output.withFormat(OutputFormat.XML)
								  .WithIndentation();	
			StreetSearchQuery streetQuery = new StreetSearchQuery((point,100000
				pagination, output, StreetType.PEDESTRIAN,false,"Avenue des c");
			String result = geolocSearchEngine.executeQueryToString(streetQuery);

Full text service

Description

• Specify one or more words
• Search for text or zip code
• Specify a GPS restriction
• Limit the results to a specific
  • Language
  • Country
  • place type
• Paginate the results
• Specify the ouput verbosity
• Tells if you want the output to be indented
• Tells that all words are required or not

Output formats and languages

• XML
• Json
• Php
• Ruby
• Python
• Georss
• ATOM

Parameters

• The searched text (required) : The text for the query, it can be a zip code, a String or one or more String.
  Examples :
  • 30980
  • Paris
  • paris france


• All words required (optional): Wether the fulltext engine should considers all the words specified as required. Default to true. possible values are true|false (or "on" when used with the rest service)


• The latitude (optional) (north-south) for the location point to search around and restrict the search results. The value is a float and can be negative. It use GPS coordinates.
  Examples :
  • -4.2


• The longitude (optional) (east-West) for the location point to search around and restrict the search results. The value is a float and can be negative. It use GPS coordinates.
  Examples :
  • 3.6


• The radius (optional) : distance from the location point in meters we'd like to search around. The value is a number > 0 if it is not specify or incorrect : The default value will be used (10 km).
  Examples :
  • 50000


• Start pagination index (optional) : The first pagination index. Numbered from 1. If the number is < 1 or not specified, it will be set to the default value : 1.


• End pagination Index (optional) : The last pagination index. if < 1 or not specified, it will be set to startindex + 10.


• The output format (optional) : The formats available are :
  
  • XML (Default)
  • PHP
  • JSON
  • PYTHON
  • RUBY
  • ATOM
  • GEORSS


• The language code (optional) : The iso 639 Alpha2 or alpha3 Language Code. Some properties as the AlternateName AdmNames and countryname belongs to a certain language code, The language parameter can limits the output of those fields to a certain language (it only apply when style parameter='style') :
  
  
  • If the language code does not exists or is not specified, properties with all the languages are retrieved
  • If it exists, the properties with the specified language code, are retrieved


Use the alpha2 code when possible, only use the alpha3 code when no alpha2 code exists for the language.



• The output style verbosity (optional) : Determines the output verbosity. 4 styles are available :
  
  
  • Short : feature_id, name, fully_qualified_name, zipcode (if city or city subdivision), placetype, country_code, country_name
  • Medium (default) : Short + lat, lon,street_type(if street),one_way(if street),length(if street), feature_class, feature_code, population, fips,
  • Medium (if country) continent, currency_code, currency_name, fips_code, isoalpha2_country_code, isoalpha3_country_code, postal_code_mask, postal_code_regex, phone_prefix, spoken_languages, tld, capital_name, area
  • Medium (adm only) level
  • Long : Medium + adm1_name, adm2_name, adm3_name, Adm4_name, adm1_code, Adm2_code, Adm3_code, Adm4_code
  • Full : Long + alternateNames, country_alternate_name, adm1_alternate_name, adm2_alternate_name. If the language parameter is specified : only alternate names with the specified language are retrive, otherwise, all the alternate names for all the languages are retrieve


For a full list and descrition of output fields : see bellow.



• The placetype(s) (optional) : limit the search to the one or more place type. place type regroups some feature class and feature code. You need to specify the class coresponding to the place type you want to search. default : search for all features


See a full list and explanation of placetype : here.



• The country code (optional) : limit the search to the specify ISO 3166 country code. Default : search in all countries




• The indentation (optional) : indents the results. Default to false. Possible values are true|false (or "on" when used with the rest service see more) Georss and Atom won't be indented for performance reasons
  
  
  
• The spellchecking (optional) : whether some suggestions should be provided if no results are found. default value is the value of the 'spellchecker.activeByDefault' option (see more).

Web service

Output fields description

Java API

			Pagination pagination = paginate().from(STARTINDEX).to(ENDINDEX);
			Output output = Output.withFormat(OUTPUTFORMAT)
					.withLanguageCode(LANGUAGECODE).withStyle(VERBOSITY)
					.WithIndentation();
					
			FulltextQuery fulltextQuery = new FulltextQuery("SEARCHEDTEXT",
					pagination, output, PLACETYPE.class, COUNTRYCODE);
					fulltextQuery.withAllWordsRequired(true)
					.around(GeolocHelper.createPoint(54.2F, -95F))
					.withRadius(1000).limitToCountryCode("FR");
			String result = fullTextSearchEngine.executeQueryToString(fulltextQuery);

			Pagination pagination = paginate().from(1).to(10);
			Output output = Output.withFormat(OutputFormat.XML)
					.withLanguageCode("FR").withStyle(OutputStyle.SHORT)
					.WithIndentation();
			FulltextQuery fulltextQuery = new FulltextQuery("Paris Texas",
					pagination, output, new String[]{City.class}, "US");
			String result = fullTextSearchEngine.executeQueryToString(fulltextQuery);

Geolocalisation service

Description

• Specify GPS position
• Limit the results to a specific place type (e.g : search all monuments around a point)
• Limit the results to a specified radius
• Paginate the results
• Tells if you want the output to be indented (currently, apply only for XML, not json for performance reasons. may change in next version)

Output formats and languages

• XML
• Json
• Php
• Ruby
• Python
• Georss
• ATOM
• YAML

Parameters

• The latitude (required) (north-south) for the location point to search around. The value is a float and can be negative. It use GPS coordinates.
  Examples :
  • -4.2


• The longitude (required) (east-West) for the location point to search around. The value is a float and can be negative. It use GPS coordinates.
  Examples :
  • 3.6


• The radius (optional) : distance from the location point in meters we'd like to search around. The value is a number > 0 if it is not specify or incorrect : The default value will be used (10 km).
  Examples :
  • 50000


• Start pagination index (optional) : The first pagination index. Numbered from 1. If the number is < 1 or not specified, it will be set to the default value : 1.


• End pagination Index (optional) : The last pagination index. if < 1 or not specified, it will be set to startindex + 10.


• The callback method name (optional), use to wrap the content into a method name, must be alphanumeric and operate only for script outputformat (json,php,ruby,python)
  Examples :
  • executeCallback :(will output "executeCallback(RESULT_FEED);" then if you evaluate this string the method will be called implicitly)


• The output format (optional) : The formats available are :
  
  • XML (Default)
  • JSON
  • Python
  • Ruby
  • PHP
  • ATOM
  • GEORSS
  • YAML



• The placetype (optional) : limit the search to the specified place type. place type regroup some feature class and feature code. you need to specify the class coresponding to the place type you want to search. default : search for all features


For performance reasons, it is highly recommended to specify a placetype (if you use web GUI, put a required parameter with the placetype)



See a full list and explanation of placetype : here.



• Distance field : Wether (or not) we want the distance field to be filled. this option is usefull when we don't care about the distance, to improve the performances. Off course, the results won't be sorted by distance. If you use a checkbox in a form to indent the results, the value will be "on" or "off", so for a simple use : the value for the web service can be "true" or "on".



• The indentation (optional) : indents the results. Default to false. Possible values are true|false. If you use a checkbox in a form to indent the results, the value will be "on" or "off", so for a simple use : the value of indent, for the geoloc web service can be "true" or "on".


Actually, only XML can be indented. It is not a bug : Indent JSON is possible but decrease performance.


• the apikey (optional) : the apikey to use if you use premium webservices this parameter is useless for local installation

Web service

Output fields description

Java API

			Point point = GeolocHelper.createPoint(LONGITUDE, LATITUDE);
			Pagination pagination = paginate().from(STARTINDEX).to(ENDINDEX);
			Output output = Output.withFormat(OUTPUTFORMAT)
								  .WithIndentation();
			GeolocQuery query = new GeolocQuery(point,RADIUS,pagination,output,PLACETYPE.class);
			String results = geolocSearchEngine.executeQueryToString(query);

			Point point = GeolocHelper.createPoint(-3.5F, 45F);
			Pagination pagination = paginate().from(1).to(10);
			Output output = Output.withFormat(OutputFormat.XML)
								  .WithIndentation();	
			GeolocQuery geolocQuery = new GeolocQuery(point,100000
					pagination, output, City.class);
			String result = geolocSearchEngine.executeQueryToString(geolocQuery);

Client libraries

Admin Interface

• Launch gisgraphy
• Open a web browser and go to http://localhost:8080/login.jsp (according that gisgraphy is running on port 8080)

Login - Password

Import data

Add / edit data

• Log into the admin interface with an admin user (default : admin/admin).
• Go to the 'Administration' menu and choose 'Add/edit/delete data'

• Enter the name (openstreetmapid or gisfeatureid are possible)
• Click the search button
• In the results list, an 'edit' button appears, click on it to get the web form to edit the features or streets

Screenshots

Security

Default admin password

Protect webServices

<Context path="/path/to/secret_files">
  <Valve className="org.apache.catalina.valves.RemoteAddrValve"
         allow="127.0.0.1" deny=""/>
</Context>

A server configuration-XML-file can look something like this:
<Configure class="org.mortbay.jetty.Server">
...
<Call name="addContext">
...
<Call name="addHandler">
<Arg>
<New class="IPAccessHandler">
<Set name="Standard">deny</Set>
<Set name="AllowIP">192.168.0.103</Set>
<Set name="AllowIP">192.168.0.100</Set>
</New>
</Arg>
</Call>

Performance

Jmeter

Database optimisations

DROP  INDEX IF EXISTS locationindex ;

CREATE INDEX locationindex
  ON gisfeature
  USING gist
  ("location");

VACUUM FULL ANALYZE;

JVM optimisations

Other tips