en:sedamo:api:sedamo_api_method_job

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.¹⁾
[addrline2] Address line #2, e.g. recipient's company name.²⁾
[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

¹⁾

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.

²⁾

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.