DAIBOLA

API: Job/Retrieve

Summary

Fetches the postal address of a given sedamo address code or an e-mail address.

URL
Authentication

Required

Parameters
  • apikey
  • format {JSON | XML | TXTNAT | TXTROM}
    • JSON returns JSON UTF-8 object
    • XML returns XML UTF-8 string
    • TXTNAT returns formatted address in international format, local address written in native characters (e.g. Chinese in Chinese characters, Russian in Cyrillic)
    • TXTROM returns formatted address in international format, local address is romanised, pure Latin characters
  • sedamo address code or emaile-mail address
  • [addrline1] Address line #1, e.g. name of the recipient.1)
  • [addrline2] Address line #2, e.g. recipient's company name.2)
  • [flagairmail] air mail {0|1}. Standard: 0
  • [flagregistered] registered mail {0|1}. Standard: 0
Response

★ = These data are always given. All other are optional or can be empty string “” or null.

  • sedamo: 8 chars, LATIN. The sedamo address code. ★
  • nameline1: 1st name line of the address, usually the name of the recipient
  • nameline2: 2nd name line, e.g. the company name.
  • sex: Gender of recipient.
  • birthday: Date of birth of the recipient.
  • phone: Fixed-line telephone number.
  • mobile: Mobile phone number.
  • fax: Telefax number.
  • language: ISO-2 code of the preffered language of the recipient.
  • addtype: Type of address (e.g., “home”). ★
  • addline1LATIN: Address line with the smallest entity of the address, e.g., apartment number. In Romanisation (pure Latin characters).
  • addline1NATIVE: Address line with the smallest entity of the address, e.g., apartment number. In native writing (e.g., Chinese characters, Cyrillic).
  • addline2LATIN: Address line with the second-smallest entity of the address, e.g., building name. In Romanisation.
  • addline2NATIVE: Address line with the second-smallest entity of the address, e.g., building name. In native writing.
  • streetLATIN: Name of the street. In Romanisation.
  • streetNATIVE: Name of the street.
  • housenoLATIN: House number or door number. In Romanisation. Alphanumerical.
  • housenoNATIVE: House number or door number. In native writing. Not purely numerical: May contain letters or graphic characters.
  • districtLATIN: Name of the city district, or village, or similar low-level place name. In Romanisation.
  • districtNATIVE: Name of the city district, or village, or similar low-level place name. In native writing.
  • cityLATIN: Name of the city or the postal town. In Romanisation or French, according to the guidelines of UPU. ★
  • cityNATIVE: Name of the city or the postal town. In native writing. ★
  • postcodeLATIN: Post code. In Romanisation. Alphanumerical. Some regions do not have a post code.
  • postcodeNATIVE: Post code. In native writing. Not purely numerical: May contain letters or graphic characters.
  • provinceLATIN: Name of the province, federal state, etc. In Romanisation. ★
  • provinceNATIVE: Name of the province, federal state, etc. In native writing. ★
  • countryISO2: 2-char ISO code of the country
  • countryISO3: 3-char ISO code of the country
  • countryENGLISH: Country name in English. ★
  • countryFRENCH: Country name in French. ★
  • countryFRENCHcap: Country name in French, ALL CAPS. ★
  • countryNATIVE: Country name in native writing. ★
  • countryDIALLINGCODE: International dailling code of the country.
  • comment: Additional comments regarding the address.
  • lastchanged: Timestamp of the last change on the address data (without the recipient's data). ★
  • latitude: Latitude in decimal writing.
  • longitude: Longitude in decimal writing.
  • address_native: Formatted address using Romanisation. ★
  • address_latin: Formatted address in native writing. Can be used as-is for printing an international address label. ★
  • var: Variable that will be handed back unchanged, e.g. for session key.
  • tracer: Variable that will be handed back unchanged and recorded by the address system.
  • status: “ok” when this request was successful. ★
Example call
sedamo_api_method_job_retrieve.php
<?php
$data = array(
     'format' => "JSON",
     'apikey' => "TestTestTestTestTestTestTestTestTestTest",
     'title' => "Mr",
     'addrline1' => "ATTN Mr John Doe",
     'addrline2' => "ACME Ltd",
     'sedamo' => "ABCDEFGH",
     'flagairmail'  => 1,
     'flagregistered'  => 0
);
 
$url = "https://api.sedamo.info/2.0/job/retrieve?" . http_build_query($data);
$json = file_get_contents($url);
$json_array = json_decode($json, true);  // 2nd parameter "true": returns result as an array 
var_dump($json_array);  // shows array 

Example with a given e-mail address, the recipient's data have been added where available.

Example of a returned JSON object:

{
    "sedamo":"ABCDEFGH",
    "nameline1":"Frau Maria Muster",
    "nameline2":"c/o Sprachschule Beispiel",
    "sex":"female",
    "birthday":"2007-06-05",
    "phone":"49203088668811",
    "mobile":"8612088668811",
    "fax":null,
    "language":"de",
    "addtype":"home",
    "addline1LATIN":"Jose-Mamon-Gebaeude",
    "addline1NATIVE":"José-Mâmon-Gebäude",
    "addline2LATIN":"",
    "addline2NATIVE":"",
    "streetLATIN":"Gefaellige-Muster-Strasse",
    "streetNATIVE":"Gefällige-Muster-Straße",
    "housenoLATIN":"56a",
    "housenoNATIVE":"56a",
    "districtLATIN":"Altstadt",
    "districtNATIVE":"Altstadt",
    "postcodeLATIN":"12345",
    "postcodeNATIVE":"12345",
    "cityLATIN":"Duesseldorf",
    "cityNATIVE":"Düsseldorf",
    "provinceLATIN":"Nordrhein-Westfalen",
    "provinceNATIVE":"Nordrhein-Westfalen",
    "countryISO2":"DE",
    "countryISO3":"DEU",
    "countryENGLISH":"Germany",
    "countryFRENCH":"Allemagne",
    "countryFRENCHcap":"ALLEMAGNE",
    "countryNATIVE":"Deutschland",
    "countryDIALLINGCODE":"49",
    "comment":"",
    "latitude":"171.2182748",
    "longitude":"66.7823445",
    "address_native":"Frau Maria Muster⏎c/o Sprachschule Beispiel⏎José-Mâmon-Gebäude⏎Altstadt⏎Gefällige-Muster-Straße 56a⏎12345 Düsseldorf⏎Germany⏎ALLEMAGNE",
    "address_latin":"Frau Maria Muster⏎c/o Sprachschule Beispiel⏎Jose-Mamon-Gebaeude⏎Altstadt⏎Gefaellige-Muster-Strasse 56a⏎12345 Duesseldorf⏎Germany⏎ALLEMAGNE",
    "var":"session::1a6b",
    "tracer":"recorded08",
    "status": "ok",
    "lastchanged": "2035-12-31 12:33:00"
}

Example of a returned XML string:

<?xml version="1.0" encoding="UTF-8"?>
<sedamo>
     <status>ok</status>
     <sedamo>ABCDEFGH</sedamo>
     <nameline1>Frau Maria Muster</nameline1>
     <nameline2>c/o Sprachschule Beispiel</nameline2>
     <sex>female</sex>
     <birthday>2007-06-05</birthday>
     <phone>49203088668811</phone>
     <mobile>8612088668811</mobile>
     <fax></fax>
     <language>de</language>
     <addtype>home</addtype>
     <addline1LATIN>Jose-Mamon-Gebaeude</addline1LATIN>
     <addline1NATIVE>José-Mâmon-Gebäude</addline1NATIVE>
     <addline2LATIN></addline2LATIN>
     <addline2NATIVE></addline2NATIVE>
     <streetLATIN>Gefaellige-Muster-Strasse</streetLATIN>
     <streetNATIVE>Gefällige-Muster-Straße</streetNATIVE>
     <housenoLATIN>56a</housenoLATIN>
     <housenoNATIVE>56a</housenoNATIVE>
     <districtLATIN>Altstadt</districtLATIN>
     <districtNATIVE>Altstadt</districtNATIVE>
     <postcodeLATIN>12345</postcodeLATIN>
     <postcodeNATIVE>12345</postcodeNATIVE>
     <cityLATIN>Duesseldorf</cityLATIN>
     <cityNATIVE>Düsseldorf</cityNATIVE>
     <provinceLATIN>Nordrhein-Westfalen</provinceLATIN>
     <provinceNATIVE>Nordrhein-Westfalen</provinceNATIVE>
     <countryISO2>DE</countryISO2>
     <countryISO3>DEU</countryISO3>
     <countryENGLISH>Germany</countryENGLISH>
     <countryFRENCH>Allemagne</countryFRENCH>
     <countryFRENCHcap>ALLEMAGNE</countryFRENCHcap>
     <countryNATIVE>Deutschland</countryNATIVE>
     <countryDIALLINGCODE>49</countryDIALLINGCODE>
     <comment></comment>
     <latitude>171.2182748</latitude>
     <longitude>66.7823445</longitude>
     <address_native>Frau Maria Muster⏎c/o Sprachschule Beispiel⏎José-Mâmon-Gebäude⏎Altstadt⏎Gefällige-Muster-Straße 56a⏎12345 Düsseldorf⏎Germany⏎ALLEMAGNE</address_native>
     <address_latin>Frau Maria Muster⏎c/o Sprachschule Beispiel⏎Jose-Mamon-Gebaeude⏎Altstadt⏎Gefaellige-Muster-Strasse 56a⏎12345 Duesseldorf⏎Germany⏎ALLEMAGNE</address_latin>
     <var>session::1a6b</var>
     <tracer>recorded08</tracer>
     <status>ok</status>
    <lastchanged>2035-12-31 12:33:00</lastchanged>
</sedamo>

Back to sedamo API start page

1)
The 1st address line might be set if e-mail is used to retrieve the address, e.g. filled with the name of the receiver. Can be overwritten.
2)
The 2nd address line might be set if e-mail is used to retrieve the address, e.g. filled with the name of the receiver. Can be overwritten.