Premium guide

This documentation will guide you on how to use premium datasets that you can buy on the premium site. The first section describes the format of the CSV files and an example on how to import it in PostgreSQL while the second, explain how to inject a Gisgraphy SQL dump. You can also download the PDF version for offline use.

CSV Dataset

File formats

Before buying you probably wonder how good is the coverage for a country and see how it looks like, select the country and see how many records we got for each dataset

Addresses

countrycode text(3) required iso-3166-2 countrycode
id bigint required  unique id that identify the address
latitude float required latitude of the address
longitude float required longitude of the address
housenumber text(255) required house number of the address. Can contains text for house number like 3A or 4 bis.
name text(255) optional additionnal information for the address. can be the name of a shop, place,...It is not the name of the person who lives there.
streetname text(255) optional name of the street 
streetid bigint optional id of the street. useful when you need to link this dataset with the street one (get more information on the street as shape for instance, see street dataset for more informations)
place text(255) optional the place . can be a suburb, borough,(more little than the city)
city text(255) optional even if the concept of city does not exists in all countries, this field relate the name of the place/ city/municipality/... where the address ids located.
adm5name text(255) optional name of the administrative division of level 5 (1 is the bigger, 5 is the more precise)
adm4name text(255) optional name of the administrative division of level 4 (1 is the bigger, 5 is the more precise)
adm3name text(255) optional name of the administrative division of level 3 (1 is the bigger, 5 is the more precise)
adm2name text(255) optional name of the administrative division of level 2 (1 is the bigger, 5 is the more precise)
adm1name text(255) optional name of the administrative division of level 1 (1 is the bigger, 5 is the more precise)
zipcode text(255) zipcode/ postcode of the address
source text(255) source of the dataset from wich the address come from, it can be a single (e.g : OSM) or composite one (e.g : OSM_OPENADDRESSES) when we have mix some information of both dataset

Streets

Note that streets can be divided in several segments to relates the difference of each segment (a street can have 2 lanes and then 3, so we split the street in several segment)

countrycode text(3) required iso-3166-2 countrycode
id bigint required  unique id that identify the street
latitude float required latitude of the street
longitude float required longitude of the street
streetname text(255) optional name of the street
streetref text(255) optional road (national/international) reference of the street 
place text(255) optional the place . can be a suburb, borough,(more little than the city)
city text(255) optional even if the concept of city does not exists in all countries, this field relate the name of the place/ city/municipality/... where the address ids located.
adm5name text(255) optional name of the administrative division of level 5 (1 is the bigger, 5 is the more precise)
adm4name text(255) optional name of the administrative division of level 4 (1 is the bigger, 5 is the more precise)
adm3name text(255) optional name of the administrative division of level 3 (1 is the bigger, 5 is the more precise)
adm2name text(255) optional name of the administrative division of level 2 (1 is the bigger, 5 is the more precise)
adm1name text(255) optional name of the administrative division of level 1 (1 is the bigger, 5 is the more precise)
zipcode text(255) zipcode/ postcode of the address
label text(500) optional representative label of the street (most often contain the street name and locality)
labelpostal text(500) optional label as it will be used to mention the streest on an enveloppe or on a postal system
fullyqualifiedname text(500) optional represents the name of the streets an all the information about the place location, zipcode and administrative divisions (usefull to do a deep search)
alternativenames text optional all the alternative names of the street seperated by '///'
streettype text(255) optional specify which type of street it is. identifying the kind of road, street or path. The value helps indicate the importance of the street (see http://wiki.openstreetmap.org/wiki/Key:highway)
azimuthstart integer optional number in degres of the azimuth (ordinal direction) at the begining of the street (useful for GPS to indicates to take to the north for instance or to calculate the difference between two streets and tell the user to take to the right, left, or to see if a street is a line or not by comparing the difference between the azimuth at the start and at the end, etc)
azimuthend integer optional number in degres of the azimuth (ordinal direction) at the end of the street (see bellow)
lanes integer optional number of lanes of the streets for this particular segment
length double optional length of the segment (a street can be composed of several segment) of the street (in meter)
maxspeed text(255) optional legal speed limit for general traffic on the forward direction (not side), if only a number stands for km/h, otherwise the unit is to be specified (mph for instance)
maxspeedbackward text(255) optional legal speed limit for general traffic on the backward direction (not side), if only a number stands for km/h, otherwise the unit is to be specified (mph for instance)
speedmode text(255) optional tells about the way the maxspeed and maxspeedbackward come from. Can be OSM when comes from openstreetmap or CALCULATED when it is based on general consideration as the speed limit in a city)
oneway boolean optional tells wether the street is a oneway street or not (no value does not mean anything, can be both)
cityid bigint optional id of the city, useful to cross the information of the street dataset and city one
surface text(255) optional tell the physical surface of the street (paved, asphalt,...)
toll boolean optional whether some fee must be paid by general traffic to use the street (no value does not mean anything, can be both)
shape text optional  shape of the street in GeoJSON format
source text(255) optional source of the dataset from wich the address come from, it can be a single (e.g : OSM) or composite one (e.g : OSM_OPENADDRESSES) when we have mix some information of both dataset
openstreetmapid bigint optional id in the openstreetmap dataset when source field is (partially or not) OSM.

CITIES (AND SUBDIVISIONS)

countrycode text(3) required iso-3166-2 countrycode
id bigint required  unique id that identify the street
latitude float required centroid latitude of the city
longitude float required centroid longitude of the street
adminlatitude float required administrative latitude of the city. Use this when you want the location of the center (not the centroid) of a city
adminlongitude float required administrative latitude of the city. Use this when you want the location of the center (not the centroid) of a city
type text(255) optional type of city (town, vilage, city)
name text(255) required name of the city
asciiname text(255) ASCII name of the city
adm5name text(255) optional name of the administrative division of level 5 (1 is the bigger, 5 is the more precise)
adm4name text(255) optional name of the administrative division of level 4 (1 is the bigger, 5 is the more precise)
adm3name text(255) optional name of the administrative division of level 3 (1 is the bigger, 5 is the more precise)
adm2name text(255) optional name of the administrative division of level 2 (1 is the bigger, 5 is the more precise)
adm1name text(255) optional name of the administrative division of level 1 (1 is the bigger, 5 is the more precise)
label text(500) optional representative label of the street (most often contain the street name and locality)
fullyqualifiedname text(500) optional represents the name of the streets an all the information about the place location, zipcode and administrative divisions (usefull to do a deep search)
alternativenames text optional all the alternative names of the street seperated by '///'
elevation integer elevation in meters
gtopo30 integer optional digital elevation model, srtm3 or gtopo30, average elevation of 3''x3'' (ca 90mx90m) or 30''x30'' (ca 900mx900m) area in meters, integer. srtm processed by cgiar/ciat
population integer optional population who lives in the city
zipcode text(255) optional the most representative zipcode to use if there is several one for this city
zipcodes text optional list of zipcodes for this city separeted by '///'
shape text optional  shape of the street in GeoJSON format
source text(255) required source of the dataset from wich the address come from, it can be a single (e.g : OSM) or composite one (e.g : OSM_OPENADDRESSES) when we have mix some information of both dataset
openstreetmapid bigint optional id in the openstreetmap dataset when source field is (partially or not) OSM.
admid bigint optional id of the adm, useful to cross the information of the city dataset and adm one
cityid bigint optional id of the city (this field is only filled whenthe entry is a suburb / city subdivision)

Adms

Note that adm are order by level

countrycode text(3) required iso-3166-2 countrycode
id bigint required  unique id that identify the street
latitude float required centroid latitude of the administrative division
longitude float required centroid longitude of the administrative division
level integer required level of the administrative division of level 5 (1 is the bigger, 5 is the more precise)
name text(255) required name of the city
asciiname text(255) optional ASCII name of the city
adm5name text(255) optional name of the administrative division of level 5 (1 is the bigger, 5 is the more precise)
adm4name text(255) optional name of the administrative division of level 4 (1 is the bigger, 5 is the more precise)
adm3name text(255) optional name of the administrative division of level 3 (1 is the bigger, 5 is the more precise)
adm2name text(255) optional name of the administrative division of level 2 (1 is the bigger, 5 is the more precise)
adm1name text(255) optional name of the administrative division of level 1 (1 is the bigger, 5 is the more precise)
label text(500) optional representative label of the street (most often contain the street name and locality)
fullyqualifiedname text(500) optional represents the name of the streets an all the information about the place location, zipcode and administrative divisions (usefull to do a deep search)
alternativenames text optional all the alternative names of the street seperated by '///'
elevation integer elevation in meters
gtopo30 integer optional digital elevation model, srtm3 or gtopo30, average elevation of 3''x3'' (ca 90mx90m) or 30''x30'' (ca 900mx900m) area in meters, integer. srtm processed by cgiar/ciat
population integer optional population who lives in the city
zipcode text(255) optional the most representative zipcode to use if there is several one for this city
zipcodes text optional list of zipcodes for this city separeted by '///'
shape text optional  shape of the street in GeoJSON format
parentid bigint optional id of the parent adm. useful to do an ADM hierarchy
source text(255) required source of the dataset from wich the address come from, it can be a single (e.g : OSM) or composite one (e.g : OSM_OPENADDRESSES) when we have mix some information of both dataset
openstreetmapid bigint optional id in the openstreetmap dataset when source field is (partially or not) OSM.

Pois

countrycode text(3) required iso-3166-2 countrycode
poitype text(50) required type of pois (restaurant, pharmacy).See poi types bellow
id bigint required  unique id that identify the street
latitude float required centroid latitude of the city
longitude float required centroid longitude of the street
type text(255) optional type of city (town, vilage, city)
name text(255) required name of the city
asciiname text(255) ASCII name of the city
adm5name text(255) optional name of the administrative division of level 5 (1 is the bigger, 5 is the more precise)
adm4name text(255) optional name of the administrative division of level 4 (1 is the bigger, 5 is the more precise)
adm3name text(255) optional name of the administrative division of level 3 (1 is the bigger, 5 is the more precise)
adm2name text(255) optional name of the administrative division of level 2 (1 is the bigger, 5 is the more precise)
adm1name text(255) optional name of the administrative division of level 1 (1 is the bigger, 5 is the more precise)
label text(500) optional representative label of the street (most often contain the street name and locality)
fullyqualifiedname text(500) optional represents the name of the streets an all the information about the place location, zipcode and administrative divisions (usefull to do a deep search)
alternativenames text optional all the alternative names of the street seperated by '///'
source text(255) required source of the dataset from wich the address come from, it can be a single (e.g : OSM) or composite one (e.g : OSM_OPENADDRESSES) when we have mix some information of both dataset
openstreetmapid bigint optional id in the openstreetmap dataset when source field is (partially or not) OSM.

poi type :admbuilding,airport,ambulance,amusepark,aqueduc,atm,bank,bar,bay,beach,bench,bridge,building,busstation,camp,camping,canyon,casino,
castle,cave,cemetery,cinema,cirque,city,cityhall,cliff,coast,courthouse,craft,customspost,dam,dentist,desert,doctor,emergencyphone,
factory,falls,farm,ferryterminal,field,firestation,fishingarea,fjord,forest,fountain,fuel,garden,gisfeature,golf,gorge,grassland,gulf,
hill,hospital,hotel,house,ice,island,lake,library,lighthouse,mall,marsh,metrostation,military,mill,mine,mole,monument,mound,mountain,
museum,nightclub,oasis,observatorypoint,ocean,operahouse,park,parking,pharmacy,picnic,plantation,policepost,politicalentity,pond,port,
postoffice,prison,pyramid,quay,rail,railroadstation,ranch,ravin,reef,religious,rental,reserve,restarea,restaurant,road,school,sea,shop,
sport,spring,stadium,strait,stream,swimmingpool,taxi,telephone,theater,toilet,tourism,tourisminfo,tower,tree,tunnel,undersea,vendingmachine,veterinary,vineyard,volcano,waterbody,zoo

Those formats are not what you search for ? You need a custom extract, contact us

The rows in CSV files got some fields that reference ids of rows in other CSV files, as an SQL table can have a foreign key that references on another column (primary key) in another table. For instance, the street CSV file has a 'cityid' field that references the id field of the City CSV file.

In addresses file, 'streetid' refers to the id field in the street file
In street file, 'cityid' refers to the id field in the city file
In city file, 'admid' refers to the id field in the adm file
In adm file, 'parentid' refers to the id field in the adm own file. The adm are sorted by level in order to first have the top level ADMs that can be referenced by other ADMs in the next lines of the file.
POIs (point of interest) are not linked to any file

It is very important to notice that those XXXID fields are optional and are sometimes not filled

So for an address, you can get the street with the streetid field that refers to the id field in the street file whith the street id , you can get the city from the cityid that refer to the id field in the city file, and then get the adm with the admid that refers to the IDin the ADM file.

Example of use

The CSV / TSV datasets is a structured format that allows being used in many ways. it can be used in Excel, or in a database, or anything that can process a text file or read a TSV file. This section only shows a common use to inject the files into a Postgres Database. (a same tutorial could be written for MySQL or Oracle).

First, you need to create the tables. You can find a SQL script that reflects the format of the CSV files. As described in the Format section (above). The files have some fields that reference ids on other files. If you want to inject files into a database and use Foreign keys mechanism, you will have to inject files in that order :

Adms
Cities
Streets
addresses

of course, if you don't have to buy all the files and skip those you haven't buy. if you buy streets, you will have a field called 'city' that reflect the city where the street is, but you won't have more information on the city. if you buy the city files, you will get alternate names, shape, population, admin center, location, ...(when available, all the fields are optional)

Gisgraphy SQL dumps

The import of data into Gisgraphy is a very long process. If you don't want to import the data by yourself, you can buy a dump of data that you can inject directly into PostgreSQL database. Once the dump downloaded (the link is provided in your dashboard or in the mail received when purchasing), you have to follow some steps.

You can also use the SQL dump with your own software or use, the SQL schema is available here

1-Install Gisgraphy

If it is not already done, You have to download and install Gisgraphy. The latest version of Gisgraphy is available at https://download.gisgraphy.com/releases/gisgraphy-latest.zip. The installation guide will help you to set it up.
Once done, follow the steps below. All those steps have to be done when gisgraphy is shutdown.

Important : You've bought a SQL dump, so you don't need to run an import of data via the admin interface. The dump you've bought is already the result of a dump that we have processed on our servers !

Those steps are independants from the installation you've choose. It can be run on Linux, Windows, Mac, on a Docker container or not.

2-Inject the dump

Go to URL given in the mail to download the dump. Note that you got 30 days to download the files.

2a-Without Docker

For those who want to go quickly, we provide (as is and without any warranty of any kind) a script to inject the dump. To use it, run the following commands (replace the words in uppercase according to your configuration) :

#clone the Github repository
git clone https://github.com/gisgraphy/gisgraphy-docker.git
cd gisgraphy-docker/dump

#put the dump file into the assets/dump/ directory
mkdir -p ./assets/dump
cp /PATH/TO/DUMP_TAR_FILE ./assets/dump/

#run the script
./inject-wo-docker.sh YOUR_POSTGRESQL_PASSWORD /PATH/TO/GISGRAPHY/DIRECTORY/

2b-With Docker

To use the dump and inject data in a Docker image :

#clone the Github repository
git clone https://github.com/gisgraphy/gisgraphy-docker.git
cd gisgraphy-docker/dump

Put the dump file into the 'assets/dump' directory :

mkdir -p ./assets/dump
cp /PATH/TO/DUMP_TAR_FILE ./assets/dump/

Build an image with the dump from a Gisgraphy Docker image (replace 'mdppostgres' and 'gisgraphyofficial' according your configuration) :

docker build  -t gisgraphydump --build-arg PGPASSWORD=mdppostgres --build-arg BASE_IMAGE=gisgraphyofficial . --build-arg SOLR_DIR=/usr/local/gisgraphy/solr/

Note that you can also use volumes create volumes on PostgreSQL data dir (/var/lib/postgresql/9.5/main) and Solr data dir (/usr/local/gisgraphy/solr/data) . See https://docs.docker.com/engine/admin/volumes/volumes/ for more infos.

2c-Step by step

For those who want to be guided, step by step, do the following instructions :

Inject the SQL dump file

Decompress the file corresponding to the SQL dump. It can be a zip or a tar file. If you are on Windows, you can use 7-zip or if you are on Linux, you can untar with the following command : tar -xvf YOURFILE.tar

If you 've already done an import, reset it :

Log on the admin page (mainMenu.html).
Go to the Admin / Reset import menu.
Confirm you want to reset the import.
Reset it.

Inject the SQL dump in PostgreSQL (custom the following line according your settings) :

pg_restore  -h 127.0.0.1 -p 5432 -U postgres  -Fc -O -v -dgisgraphy /PATH/TO/FILES/dump_localhost.gz

Run the createGISTIndex.sql file that is in the sql directory of the Gisgraphy distribution. (custom the following line according to your settings)

psql -U postgres -h 127.0.0.1 -d gisgraphy -f ./sql/createGISTIndex.sql

If you got a ‘duplicate entry’ error message in the User or in the Profile table. Simply ignore it ! It is because you’ve already got some users in the database.

Setup the full-text engine (optional)

This section is optional and could be skipped if no full-text engine dump (Solr) is provided. You only need the full-text engine if you use, geocoding, full-text / autocompletion web services. If you only use reverse geocoding, street search, and nearby web service, you can skip this section. It will save disk space (that will have no impact on performance)

Unzip the full-text engine dump named 'data.zip'. It contains a directory called 'data'.
Copy (or replace) this directory data in /SolR directory in the Gisgraphy distribution.

That’s all ! (Re)start Gisgraphy with the launch.sh script and use it

3-Support

If you got problems, you can use the contact page or send us a mail.