API du generateur d'adresses residentielles reelles

Authentification

Sauf pour l'etat, la disponibilite et OpenAPI, chaque endpoint exige un Bearer Token cree dans la console. Les jetons gerent les droits de lecture ou generation, la limite par minute et expiration.

Authorization: Bearer YOUR_API_TOKEN

GET/api/v1/health

Droit: public

Verifie que le processus d'API est disponible.

Parametres

Aucun parametre de requete.

Exemples d'appel

curl "https://address.example/api/v1/health" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/health",
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/health");
const payload = await response.json();
console.log(payload);

Reponse reussie

{
  "status": "ok"
}

GET/api/v1/ready

Droit: public

Verifie que l'API et PostgreSQL sont prets a servir le trafic.

Parametres

Aucun parametre de requete.

Exemples d'appel

curl "https://address.example/api/v1/ready" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/ready",
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/ready");
const payload = await response.json();
console.log(payload);

Reponse reussie

{
  "status": "ready"
}

GET/api/v1/countries

Droit: read

Liste les pays, capacites, volumes et raccourcis.

Parametres

Aucun parametre de requete.

Exemples d'appel

curl "https://address.example/api/v1/countries" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/countries",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/countries", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

Reponse reussie

{
  "data": [
    {
      "code": "US",
      "residentialAvailable": true,
      "residentialCount": 50000,
      "generationMode": "synchronized-pool"
    }
  ]
}

GET/api/v1/availability

Droit: read

Renvoie la liste legere de disponibilite residentielle.

Parametres

Aucun parametre de requete.

Exemples d'appel

curl "https://address.example/api/v1/availability" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/availability",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/availability", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

Reponse reussie

{
  "data": [
    {
      "code": "US",
      "residentialAvailable": true
    }
  ]
}

GET/api/v1/client-context

Droit: read

Resout le pays et le contexte geographique de l'adresse IP.

Parametres

ipFacultatif · query · stringOptional IPv4 or IPv6 address; omitted means the request IP.

Exemples d'appel

curl "https://address.example/api/v1/client-context?ip=198.51.100.7" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/client-context?ip=198.51.100.7",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/client-context?ip=198.51.100.7", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

Reponse reussie

{
  "data": {
    "country": "US",
    "region": "California",
    "city": "Los Angeles",
    "matchLevel": "city"
  }
}

GET/api/v1/locations/search

Droit: read

Recherche regions, villes, districts ou codes postaux avec pagination.

Parametres

countryFacultatif · query · string · Par defaut: USISO 3166-1 alpha-2 country code.

fieldFacultatif · query · string · Par defaut: cityCatalog field to return.

qFacultatif · query · stringOptional case-insensitive search text.

regionFacultatif · query · stringExact parent region value.

regionIdFacultatif · query · stringStable parent region ID.

cityIdFacultatif · query · stringStable parent city ID.

residentialFacultatif · query · boolean · Par defaut: falseRestrict counts to published residential records.

cursorFacultatif · query · stringOpaque cursor returned by the previous page.

limitFacultatif · query · integer · Par defaut: 100 · 20-200Page size from 20 through 200.

Exemples d'appel

curl "https://address.example/api/v1/locations/search?country=US&field=city&regionId=1416&limit=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/locations/search?country=US&field=city&regionId=1416&limit=100",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/locations/search?country=US&field=city&regionId=1416&limit=100", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

Reponse reussie

{
  "data": {
    "cities": [
      {
        "id": "example-city",
        "value": "Los Angeles",
        "availableCount": 120
      }
    ],
    "total": 1,
    "nextCursor": null
  }
}

GET/api/v1/generate

Droit: generate

Genere aleatoirement une adresse residentielle publiee et un profil de test.

Parametres

countryFacultatif · query · string · Par defaut: USISO 3166-1 alpha-2 country code.

regionFacultatif · query · stringExact first-level region value.

regionIdFacultatif · query · stringStable region ID from location search.

cityFacultatif · query · stringExact city value.

cityIdFacultatif · query · stringStable city ID from location search.

districtFacultatif · query · stringExact district value where supported.

districtIdFacultatif · query · stringStable district ID from location search.

postcodeFacultatif · query · stringExact postcode value.

postcodeIdFacultatif · query · stringStable postcode ID from location search.

modeFacultatif · query · stringUse ip-region to match the request or supplied IP.

ipFacultatif · query · stringIPv4 or IPv6 used with ip-region mode.

qFacultatif · query · stringText that must occur in the selected address components.

strategyFacultatif · query · string · Par defaut: randomSelection strategy; both modes select from the synchronized database.

residentialFacultatif · query · boolean · Par defaut: trueLegacy compatibility flag; generation always returns residential records.

seedFacultatif · query · stringOptional reproducible random seed.

requestIdFacultatif · query · stringCaller-provided request correlation ID.

Exemples d'appel

curl "https://address.example/api/v1/generate?country=US&region=California&requestId=YOUR_REQUEST_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/generate?country=US&region=California&requestId=YOUR_REQUEST_ID",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/generate?country=US&region=California&requestId=YOUR_REQUEST_ID", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

Reponse reussie

{
  "data": {
    "requestId": "YOUR_REQUEST_ID",
    "country": "US",
    "mode": "residential",
    "sourcesTried": [
      "address-pool-v2"
    ],
    "result": {
      "address": {
        "id": "address-id",
        "countryCode": "US",
        "formattedAddress": "Example address"
      }
    }
  }
}

POST/api/v1/generate/batch

Droit: generate

Genere jusqu'a 50 adresses residentielles avec filtres structures, exclusions et unicite.

Parametres

countRequis · body · integer · 1-50Number of addresses to generate.

filtersRequis · body · objectCountry and exact administrative, postcode, or text filters.

optionsFacultatif · body · objectRandomness, uniqueness, strategy, and request correlation options.

excludeAddressIdsFacultatif · body · arrayAddress IDs that must not be returned.

Exemples d'appel

curl -X POST "https://address.example/api/v1/generate/batch" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "count": 3,
  "filters": {
    "country": "US",
    "region": "California",
    "city": "Los Angeles"
  },
  "options": {
    "unique": true,
    "strategy": "random",
    "seed": "example-seed"
  },
  "excludeAddressIds": []
}'

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/generate/batch",
    headers={"Authorization":"Bearer YOUR_API_TOKEN","Content-Type":"application/json"},
    data=json.dumps({"count":3,"filters":{"country":"US","region":"California","city":"Los Angeles"},"options":{"unique":true,"strategy":"random","seed":"example-seed"},"excludeAddressIds":[]}),
    method="POST"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/generate/batch", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "count": 3,
    "filters": {
      "country": "US",
      "region": "California",
      "city": "Los Angeles"
    },
    "options": {
      "unique": true,
      "strategy": "random",
      "seed": "example-seed"
    },
    "excludeAddressIds": []
  })
});
const payload = await response.json();
console.log(payload);

Reponse reussie

{
  "data": {
    "requestId": "batch-request-id",
    "requestedCount": 3,
    "returnedCount": 3,
    "unique": true,
    "results": [
      {
        "address": {
          "id": "address-id",
          "countryCode": "US"
        }
      }
    ]
  }
}

GET/api/v1/locations/hierarchy

Droit: read

Liste les subdivisions administratives ou codes postaux directs d'un pays, d'une region ou d'une ville.

Parametres

countryRequis · query · stringISO 3166-1 alpha-2 country code.

childTypeRequis · query · stringChild catalog type to return.

parentTypeFacultatif · query · string · Par defaut: countryType of parent identified by parentId.

parentIdFacultatif · query · stringStable region or city ID; omit for a country parent.

qFacultatif · query · stringOptional child-name search text.

residentialFacultatif · query · boolean · Par defaut: trueInclude residential availability and disable uncovered options.

cursorFacultatif · query · stringOpaque cursor returned by the previous page.

limitFacultatif · query · integer · Par defaut: 100 · 20-200Page size from 20 through 200.

Exemples d'appel

curl "https://address.example/api/v1/locations/hierarchy?country=US&parentType=region&parentId=1416&childType=city&limit=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/locations/hierarchy?country=US&parentType=region&parentId=1416&childType=city&limit=100",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/locations/hierarchy?country=US&parentType=region&parentId=1416&childType=city&limit=100", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

Reponse reussie

{
  "data": {
    "parent": {
      "type": "region",
      "id": "1416"
    },
    "childType": "city",
    "children": [
      {
        "id": "example-city",
        "value": "Los Angeles",
        "availableCount": 120
      }
    ],
    "total": 1,
    "nextCursor": null
  }
}

GET/api/v1/coverage

Droit: read

Indique les trois regles de completion de synchronisation pour les pays actifs.

Parametres

countryFacultatif · query · stringOptional ISO country code filter.

includeCompleteFacultatif · query · boolean · Par defaut: trueInclude countries that already satisfy all three rules.

Exemples d'appel

curl "https://address.example/api/v1/coverage?country=US&includeComplete=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/coverage?country=US&includeComplete=true",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/coverage?country=US&includeComplete=true", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

Reponse reussie

{
  "data": {
    "countries": [
      {
        "countryCode": "US",
        "complete": false,
        "rules": {
          "total": {
            "current": 42000,
            "target": 50000,
            "met": false
          },
          "administrativeCoverage": {
            "actual": 0.98,
            "target": 1,
            "met": false
          },
          "regionalMinimums": {
            "actual": 0.95,
            "target": 1,
            "met": false
          }
        }
      }
    ]
  }
}

GET/api/v1/addresses/{id}

Droit: read

Recupere une adresse synchronisee actuellement publiee par son identifiant.

Parametres

idRequis · path · stringAddress ID returned by generate or batch generation.

Exemples d'appel

curl "https://address.example/api/v1/addresses/pool-v2-address-id" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/addresses/pool-v2-address-id",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/addresses/pool-v2-address-id", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

Reponse reussie

{
  "data": {
    "address": {
      "id": "pool-v2-address-id",
      "countryCode": "US",
      "formattedAddress": "Example address"
    }
  }
}

POST/api/v1/address-translation

Droit: generate

Traduit une adresse synchronisee vers une langue prise en charge.

Parametres

addressIdRequis · body · stringAddress ID returned by generate.

targetLocaleRequis · body · stringTarget display locale.

Exemples d'appel

curl -X POST "https://address.example/api/v1/address-translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "addressId": "address-id",
  "targetLocale": "zh-CN"
}'

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/address-translation",
    headers={"Authorization":"Bearer YOUR_API_TOKEN","Content-Type":"application/json"},
    data=json.dumps({"addressId":"address-id","targetLocale":"zh-CN"}),
    method="POST"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/address-translation", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "addressId": "address-id",
    "targetLocale": "zh-CN"
  })
});
const payload = await response.json();
console.log(payload);

Reponse reussie

{
  "data": {
    "components": {
      "street": "示例街道",
      "houseNumber": "20"
    },
    "lines": [
      "示例地址"
    ],
    "singleLine": "示例地址"
  }
}

GET/api/v1/data-health

Droit: read

Indique la sante des pools synchronises et les erreurs de configuration.

Parametres

Aucun parametre de requete.

Exemples d'appel

curl "https://address.example/api/v1/data-health" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/data-health",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/data-health", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

Reponse reussie

{
  "data": {
    "healthy": true,
    "countries": [
      {
        "code": "US",
        "ready": true,
        "count": 50000
      }
    ],
    "configurationErrors": []
  }
}

Erreurs

400INVALID_REQUEST

401UNAUTHORIZED

404NO_POOL_COVERAGE / ADDRESS_NOT_FOUND

429RATE_LIMITED · Retry-After: 60

500 / 503INTERNAL_ERROR / SERVICE_UNAVAILABLE