Kysymykset · Osoitteet

Onko olemassa API osoitteiden normalisointiin?

Mitä kutsu tekee

Yhteystiedon tarkistuksen päätepiste muotoilee osoitteen maansa postimuotoon ja sen mukana tulevan nimen. Se lukee kadun, talonumeron, postinumeron ja kaupungin yhdessä, ei kenttä kerrallaan, ja ilmoittaa jokaisen korjauksen. Maa annetaan kentässä country_code (ISO 3166-1) tai kentässä country, kirjoitettuna miten tahansa.

Yksi yhteystieto kerrallaan pyynnön rungossa tai luettelo kentässä items, enintään viisisataa kutsua kohti. Jokainen kutsu tarvitsee tokenin, jonka luot tililläsi rekisteröitymisen jälkeen ja välität otsakkeessa Authorization: Bearer. Tokenille voi antaa vanhenemispäivän tai jättää sen voimaan, kunnes peruutat sen.

Miten tulos palautuu

Vastauksessa on saman osoitteen kaksi muotoa: luettava tarkemerkkeineen ja postimuoto tarrojen tulostukseen, isoin kirjaimin. Tarvitset molempia eri syistä: ensimmäistä osoitteen näyttämiseen käsittelijälle tai käyttöliittymässä, toista varsinaiseen tulostukseen.

Niiden mukana tulee tulos avainsanoina — oikein, muutettu ja mikä muuttui kenttä kentältä, tai tarkistettava, kun osoitetta ei voi rakentaa uudelleen varmasti, syy selkokielellä: katua ei löytynyt kunnasta, tiedot riittämättömät, talonumeroa ei löytynyt. Mitään ei koskaan korjata hiljaa: jos muutamme jotain, kerromme sen, ja jos emme ole varmoja, sanomme senkin yhtä selvästi arvaamisen sijaan. Siellä, missä rekisteri on käytössä, saat myös talonumeron koordinaatit, kunnan koodin ja niissä kaupungeissa, joissa se on, kaupunginosan.

Yksittäinen osoite tai eräajot

Alle viidensadan pyynnön saat vastauksen heti, samassa kutsussa: tyypillinen tapaus on rekisteröitymislomake tai kassa, jossa osoite on tarkistettava sillä hetkellä, kun käyttäjä sen kirjoittaa. Suuremmille luetteloille, enintään satatuhatta osoitetta kerralla, lisää "async": true: pyyntö palauttaa heti työkoodin ja käsittely siirtyy jonoon, samaan, joka hoitaa sivustolta ladatut eräajot. Luet tuloksen takaisin GET-kutsulla samaan päätepisteeseen koodin kanssa, JSON-muodossa tai, jos tarvitset ladattavan tiedoston, CSV-muodossa.

Automaattinen täydennys lomakkeisiisi

Jos rakennat osoitelomaketta, /api/v1/suggest antaa automaattisen täydennyksen käyttäjän kirjoittaessa: katu, kaupunki ja talonumero ehdotetaan sitä mukaa, ja kenttä on valinnassa jo tarkistettu sen sijaan, että se pitäisi tarkistaa jälkikäteen erillisellä kutsulla. Käytettävä omalta palvelimeltasi, joka toimii välityspalvelimena päätepisteeseen: token ei saa koskaan näkyä loppukäyttäjän selaimessa.

Milloin integrointi on järkevää

Se on järkevää, kun osoite tulee rekisteriin yhä uudelleen, ei kertaluonteisesti: rekisteröitymislomake, verkkokaupan kassa, useasta kanavasta täyttyvä CRM. Sen tarkistaminen siinä, sillä hetkellä kun se saapuu, estää virheellisten osoitteiden kasautumisen, jotka on sitten siivottava erissä ennen jokaista postitusta. Jos sinulla sen sijaan on jo luettelo, joka on korjattava kerran, on yksinkertaisempaa ladata se Excel- tai CSV-tiedostona sivustolta: sama moottori, ilman riviäkään koodia.

Virheet, rajat ja täydellinen dokumentaatio

Jokaisella vastauksella on tapahtunutta vastaava HTTP-koodi: 401, jos token puuttuu tai on virheellinen, 413, jos erä ylittää rajan, 429, jos olet ylittänyt sallitun pyyntömäärän minuutissa, 402, jos krediitti ei riitä kutsuun. Osoite, jota ei voi normalisoida, ei ole API-virhe: vastaus tulee joka tapauksessa tuloksen kanssa, joka selittää miksi.

API-sivulta löydät kaikki päätepisteet — osoite, duplikaattien poisto, sähköposti, puhelin, verkkosivusto, nimen rikastus — parametreineen, curl-esimerkkeineen ja virhekoodeineen kokonaisuudessaan. Jos työskentelet spesifikaatioita tuovalla työkalulla, on myös openapi.json.

Minimaalinen kutsu

Täydellinen vastaus sisältää myös postimuodon, jokaisen muutetun kentän yksityiskohdat, talonumeron koordinaatit ja tiedot sellaisina kuin lähetit ne, vertailua varten.