API Documentation

Integrate country-specific test address data into your apps with our REST API. Use the endpoint directly, narrow results by location, and follow the code examples below.

Overview

The Placevy API provides country-specific address data from 190+ countries for testing and development workflows. Generate a random result, narrow it by state, city, or county, or verify an address programmatically.

Base URL

https://www.placevy.com/api/v1

address/day

Anonymous

∞

Unlimited

Signed-in Account

∞

Unlimited

Developer (API)

Authentication

All API requests require an API key passed in the X-API-Key header.

X-API-Key: ak_your_api_key_here

Getting Your API Key: Sign up and create an API key in your dashboard.

API Access: Signed-in users can access the API through their account.

Generate Random Address

Generates a country-specific test address result from the specified country.

GET/api/v1/generate

Query Parameters

country(required) - Country name (e.g., "Slovakia", "United States")

state(optional) - Exact state, province, or region label to filter by (e.g., "Ohio")

city(optional) - Exact city label; use it with the matching state value

county(optional) - Exact county label for a narrower result

quantity(optional) - Number of results from 1 to 10; the response contains one object for 1 and an array for more than 1

Location filters use the stored labels for the selected country. Start with the country page selector when you need the exact state or city spelling.

Example Request

curl -X GET "https://www.placevy.com/api/v1/generate?country=Slovakia" \
  -H "X-API-Key: ak_your_api_key"

Success Response (200)

{
  "success": true,
  "data": {
    "id": "loc-183372096",
    "display_address": "Slovakia, 3231/2A, Antona Bernoláka, Staré mesto...",
    "complete_address": {
      "house_number": "3231/2A",
      "road": "Antona Bernoláka",
      "city": "Žilina",
      "postcode": "010 01",
      "country": "Slovensko",
      "country_code": "sk"
    },
    "latitude": "49.21968205",
    "longitude": "18.73965173905775"
  }
}

Verify Address

Verifies if an address exists in the database.

POST/api/v1/verify

Example Request

curl -X POST "https://www.placevy.com/api/v1/verify" \
  -H "X-API-Key: ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "complete_address": {
      "city": "Bratislava",
      "country_code": "sk"
    },
    "latitude": "48.1486",
    "longitude": "17.1077"
  }'

Success Response (200)

{
  "success": true,
  "valid": true
}

Error Handling

The API uses conventional HTTP response codes to indicate success or failure.

400Invalid Country

{
  "error": "INVALID_COUNTRY",
  "message": "Country code 'xx' is not supported",
  "status": 400
}

401Unauthorized

{
  "error": "UNAUTHORIZED",
  "message": "Invalid API key or credentials",
  "status": 401
}

429Quota Exceeded

{
  "error": "QUOTA_EXCEEDED",
  "message": "Daily quota exceeded. Used: 1/1. Create an account to continue.",
  "status": 429
}

Rate Limits

Our API uses clear rate limits to support reliable service.

Anonymous: 1 request per day (no signup required)
Registered Users: Unlimited requests

Supported Countries

We support address generation for 190+ countries worldwide.

View the complete list of supported countries:

Browse all countries

Ready to get started?

Get API Key