My account

Username	null
Email	null
API KEY	null

Welcome to the PERDIDO REST API

This document describes how to get started using the PERDIDO API.

Registration

To use the PERDIDO REST API you must be registered.

Register

After your registration you will receive an API key by e-mail to access the PERDIDO API services.
Then you will have also access to the online demonstration tool of the PERDIDO Geoparsing service dedicated to hiking descriptions.

Top

POS processing service

This service calls an external Part-of-Speech tagger and transforms the output to be compliant with the input of the Unitex platform.

Resource Information

We provide two services for the POS processing, one providing a XML-TEI compliant output:


		
	GET/POST http://erig.univ-pau.fr/PERDIDO/api/pos/txt_xml/?[params]

Try it!

and another one providing an unitex ouput:


		
	GET/POST http://erig.univ-pau.fr/PERDIDO/api/pos/txt_unitex/?[params]

Try it!

Method Parameters

The table below shows the list of the different parameters.

Parameter	Type	Description
api_key	(string)	Your API key
lang	(string)	[Optional]. French (default), Spanish or English
content	(string)	Textual content to annotate
POStagger	(string)	[Optional]. treetagger (default),Stanford NLP or talismane (only for French)

Data Format

The code below shows the JSON API data model defined for POST requests.


{
	"request":{
		"api_key":"[YOUR-API-KEY]",
		"lang":"French",
		"content":"Je visite la ville de Pau.",
		"POStagger":"treetagger",
	}
}

Output Format


{Je,je.PRO+PpvIL} {visite,visiter.V} {les,le.DET+ART} {villages,village.N} {au,au.PREPDET} {sud,sud.N} {de,de.PREP} {Pau,Pau.NPr} {.,..SEN}


<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <text>
    <body>
      <p>
        <s>
          <w lemma="je" pos="PRO:PER">Je</w>
          <w lemma="visiter" pos="VER:pres">visite</w>
          <w lemma="le" pos="DET:ART">la</w>
          <w lemma="ville" pos="NOM">ville</w>
          <w lemma="de" pos="PRP">de</w>
          <w lemma="Pau" pos="NAM">Pau</w>
          <w lemma="." pos="SENT">.</w>
        </s>
      </p>
    </body>
  </text>  
</TEI>

Top

Expanded named entity recognition and spatial classification service

The expanded named entity annotation service annotates expanded named entities and their associated spatial relations using a multi-layer annotation language based on TEI and described in:

Moncla, L. and Gaio, M. : A multi-layer markup language for geospatial semantic annotations. In the 9th Workshop on Geographic Information Retrieval (GIR'15), Paris, France (2015)

The PERDIDO REST API provides several services for annotating expanded named entities.

From tagged text

Named Entity Recognition without classification (using POS-tagged text):


		
	GET/POST http://erig.univ-pau.fr/PERDIDO/api/ner/pos_xml/?[params]

Try it!

Named Entity Recognition and Classification (using XML/TEI-tagged text):


		
	POST http://erig.univ-pau.fr/PERDIDO/api/nerc/ner_xml/?[params]

Method Parameters

The table below shows the list of the different parameters.

Parameter	Type	Description
api_key	(string)	Your API key
lang	(string)	[Optional]. French (default) or Spanish
content	(string)	Textual content to annotate

From raw text

Named Entity Recognition without classification:


		
	GET/POST http://erig.univ-pau.fr/PERDIDO/api/ner/txt_xml/?[params]

Try it!

Named Entity Recognition and Classification:


		
	GET/POST http://erig.univ-pau.fr/PERDIDO/api/nerc/txt_xml/?[params]

Try it!

Method Parameters

The table below shows the list of the different parameters.

Parameter	Type	Description
api_key	(string)	Your API key
lang	(string)	[Optional]. French (default) or Spanish
content	(string)	Textual content to annotate
POStagger	(string)	[Optional]. treetagger (default) or talismane (only for French)
IGN	(boolean)	[Optional]. true (default) or false
GeoName	(boolean)	[Optional]. true (default) or false
OSM	(boolean)	[Optional]. true (default) or false

Output Format

Named Entity Recognition without classification:


<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <s>
    <w lemma="je" type="PRO">Je</w>
    <phr type="motion">
      <w lemma="visiter" type="V" subtype="motion_median">visite</w>
      <rs type="rel" subtype="name">
        <term type="N">
          <w lemma="le" type="DET">les</w>
          <w lemma="village" type="N">villages</w>
        </term>
        <w lemma="au" type="PREPDET">au</w>
        <term type="offset" subtype="orientation">
          <w lemma="sud" type="A">sud</w>
          <w lemma="de" type="PREP">de</w>
        </term>
        <rs type="expandedName">
          <term type="N">
            <w lemma="le" type="DET">la</w>
            <w lemma="ville" type="N">ville</w>
          </term>
          <w lemma="de" type="PREP">de</w>
          <name>
            <w lemma="Pau" type="NPr">Pau</w>
          </name>
        </rs>
      </rs>
    </phr>
    <pc force="strong">.</pc>
  </s>
</TEI>

Named Entity Recognition and Classification:


<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <s>
    <w lemma="je" type="PRO">Je</w>
    <phr type="motion">
      <w lemma="visiter" type="V" subtype="motion_median">visite</w>
      <placeName>
        <geogFeat>
          <w lemma="le" type="DET">les</w>
          <w lemma="village" type="N">villages</w>
        </geogFeat>
        <w lemma="au" type="PREPDET">au</w>
        <offset type="orientation">
          <w lemma="sud" type="A">sud</w>
          <w lemma="de" type="PREP">de</w>
        </offset>
        <placeName>
          <geogFeat>
            <w lemma="le" type="DET">la</w>
            <w lemma="ville" type="N">ville</w>
          </geogFeat>
          <w lemma="de" type="PREP">de</w>
          <name>
            <w lemma="Pau" type="NPr">Pau</w>
          </name>
        </placeName>
      </placeName>
    </phr>
    <pc force="strong">.</pc>
  </s>
</TEI>

Top

GetToponyms service

This service returns the list of toponyms found in the input text with their geo-location.

From annotated text


		
		POST http://erig.univ-pau.fr/PERDIDO/api/toponyms/ner_json/?[params]

Try it!

Method Parameters

The table below shows the list of the different parameters.

Parameter	Type	Description
api_key	(string)	Your API key
lang	(string)	[Optional]. French (default) or Spanish
content	(string)	Textual content to annotate
disambiguationLevel	(int)	[Optional]. 0 , 1 (default) , 2
IGN	(boolean)	[Optional]. true (default) or false
GeoName	(boolean)	[Optional]. true (default) or false
OSM	(boolean)	[Optional]. true (default) or false

The disambiguationLevel parameter refers to the toponym disambiguation.

0: no disambiguation process will be applied.
1: (default) duplicate points coming from several geographical databases will be removed.
2: (dedicated for hiking descriptions) ambiguities will be removed according to the method described in:

Moncla, L., Renteria-Agualimpia, W., Nogueras-Iso, J. and Gaio, M.: Geocoding for texts with fine-grain toponyms: an experiment on a geoparsed hiking descriptions corpus. In the 22th ACM SIGSPATIAL Conference, Dallas, Texas, USA (2014)

From raw text


		
		GET/POST http://erig.univ-pau.fr/PERDIDO/api/toponyms/txt_json/?[params]

Try it!

Method Parameters

The table below shows the list of the different parameters.

Parameter	Type	Description
api_key	(string)	Your API key
lang	(string)	French (default) or Spanish
content	(string)	Textual content to annotate
POStagger	(string)	[Optional]. treetagger (default) or talismane (only for French)
disambiguationLevel	(int)	[Optional]. 0 , 1 (default) , 2

Output Format


[
{"title": "Pau","findName": "le pau","country": "FR","continent": "EU","feature": "Lieu-dit habité","featureText": "ville","lat": "0.2887560675715038","lng": "46.734130308147485","elevation": "0.0","src": "IGN","nb": "2","verbe": "visite"},
{"title": "Pau","findName": "le pau","country": "FR","continent": "EU","feature": "Sommet","featureText": "ville","lat": "3.758625338371116","lng": "44.63698997505299","elevation": "0.0","src": "IGN","nb": "2","verbe": "visite"}
]

Top

GeoJson, KML or GPX

This service returns the list of toponyms found in the input text with their geo-location, using standard output format (GeoJSON, KML, GPX).

From a PERDIDO JSON file


		
		GET/POST http://erig.univ-pau.fr/PERDIDO/api/toponyms/json_gps/?[params]

Try: Get the GeoJson file URL Try: Get the GeoJson content

Method Parameters

The table below shows the list of the different parameters.

Parameter	Type	Description
api_key	(string)	Your API key
content	(JSONArray)	Content of the PERDIDO JSON file produced by the GetToponyms service.
outputFormat	(string)	GeoJson (default), KML, GPX
getURL	(string)	true, false (default)

Output Format


{
   "features": [{
      "geometry": {
         "coordinates": [
            -0.3707962381672617,
            43.29509998018166
         ],
         "type": "Point"
      },
      "type": "Feature",
      "properties": {"name": "Pau"}
   }],
   "type": "FeatureCollection"
}


<kml xmlns="http://www.opengis.net/kml/2.2">
   <Placemark>
      <name>Pau</name>
      <description>pau</description>
      <Point>
         <coordinates>43.29509998018166,-0.3707962381672617</coordinates>
      </Point>
   </Placemark>
</kml>


<gpx xmlns="http://www.topografix.com/GPX/1/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" creator="byHand" version="1.1" xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
   <wpt lat="43.29509998018166" lon="-0.3707962381672617">
      <ele>0.0</ele>
      <time>0000-00-00000:00:000</time>
      <name>Pau</name>
   </wpt>
</gpx>

Top

Example of POST request

Java



String request = "{\"request\":{\"api_key\":\"--YOUR_API_KEY--",\"lang\":\"French\",\"content\":\"Ceci est un exemple.\"}}";
JSONObject jsonObject = new JSONObject(request);

URL url = new URL("--URL--");
URLConnection connect = url.openConnection();
connect.setDoOutput(true);
connect.setRequestProperty("Content-Type","application/json");

OutputStreamWriter out = new OutputStreamWriter(connect.getOutputStream());
out.write(jsonObject.toString());
out.close();

BufferedReader in = new BufferedReader(new InputStreamReader(connect.getInputStream()));

String line = null;
while ((line = in.readLine()) != null) {
	response += line;
}

System.out.println("Result: "+response);
in.close();

Top

View examples

Extracting and Retrieving Displacements from textual Documents

Options

My account

Change password

Please sign in

Trial application form

Contact us

Welcome to the PERDIDO REST API

Registration

POS processing service

Resource Information

Method Parameters

Data Format

Output Format

Expanded named entity recognition and spatial classification service

From tagged text

Named Entity Recognition without classification (using POS-tagged text):

Named Entity Recognition and Classification (using XML/TEI-tagged text):

Method Parameters

From raw text

Named Entity Recognition without classification:

Named Entity Recognition and Classification:

Method Parameters

Output Format

Named Entity Recognition without classification:

Named Entity Recognition and Classification:

GetToponyms service

From annotated text

Method Parameters

From raw text

Method Parameters

Output Format

GeoJson, KML or GPX

From a PERDIDO JSON file

Method Parameters

Output Format

Example of POST request

Java