| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| en:sedamo:api:sedamo_api_method_job_retrieve [2022/03/26 15:16] – ↷ Page moved from i:sedamo:api:sedamo_api_method_job_retrieve to en:sedamo:api:sedamo_api_method_job_retrieve admin | en:sedamo:api:sedamo_api_method_job_retrieve [2023/05/25 17:45] (current) – admin |
|---|
| | ====== API: Job/Retrieve ====== |
| |
| | == Summary == |
| | Fetches the postal address of a given //sedamo// address code or an e-mail address. |
| | |
| | == URL == |
| | https://api.sedamo.info/2.0/job/retrieve |
| | |
| | == 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 **nat**ive characters (e.g. Chinese in Chinese characters, Russian in Cyrillic) |
| | * TXTROM returns formatted address in international format, local address is **rom**anised, pure Latin characters |
| | * ''sedamo'' address code __or__ ''email''e-mail address |
| | * [''addrline1''] Address line #1, e.g. name of the recipient.((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.)) |
| | * [''addrline2''] Address line #2, e.g. recipient's company name.((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.)) |
| | * [''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 == |
| | |
| | <code PHP 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 |
| | </code> |
| | |
| | Example with a given e-mail address, the recipient's data have been added where available. |
| | |
| | Example of a returned JSON object: |
| | |
| | <code JAVA> |
| | { |
| | "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" |
| | } |
| | </code> |
| | |
| | Example of a returned XML string: |
| | <code XML> |
| | <?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> |
| | </code> |
| | |
| | |
| | [[en:sedamo:api:start|Back to sedamo API start page]] |