Both sides previous revisionPrevious revisionNext revision | Previous revision |
en:sedamo:api:sedamo_api_method_job_retrieve [2022/03/26 15:28] – 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]] |