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: Latidtude 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 of a returned JSON object:

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

{
    "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>
          <###> FIXME </###>
          <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.