API Documentation

Integrate Mocloc's random address generation into your applications

Getting Started

Our REST API provides programmatic access to random address generation. All endpoints return JSON responses and require no authentication for basic usage.

Base URL

https://mocloc.com/api/v1

Countries Endpoint

Get All Countries

GET /countries

Returns a list of all available countries with their ISO codes.

Example Response


[
  {
    "country": "Afghanistan",
    "iso_code": "AF",
    "has_postal_codes": true,
    "postal_code_format": "NNNN",
    "min_length": 4,
    "max_length": 4,
    "allows_letters": false,
    "allows_numbers": true
  },
  {
    "country": "Åland",
    "iso_code": "AX",
    "has_postal_codes": true,
    "postal_code_format": "NNNNN, CC-NNNNN",
    "min_length": 5,
    "max_length": 7,
    "allows_letters": true,
    "allows_numbers": true
  },
  {
    "country": "Albania",
    "iso_code": "AL",
    "has_postal_codes": true,
    "postal_code_format": "NNNN",
    "min_length": 4,
    "max_length": 4,
    "allows_letters": false,
    "allows_numbers": true
  },
]

Get Specific Country

GET /countries/{isoCode}

Returns details for a specific country by ISO code.

Example Request

curl https://mocloc.com/api/v1/countries/US

Example Response


{
  "country": "United States",
  "iso_code": "US",
  "has_postal_codes": true,
  "postal_code_format": "NNNNN, NNNNN-NNNN",
  "min_length": 5,
  "max_length": 9,
  "allows_letters": false,
  "allows_numbers": true
}

Addresses Endpoint

Generate Random Addresses

GET /addresses/{isoCode}

Generate random addresses for a specific country.

Query Parameters

Parameter Type Default Description
count integer 10 Number of addresses to generate (1-50)

Example Request

curl https://mocloc.com/api/v1/addresses/US?count=5

Example Response


[
  {
    "country": "United States",
    "iso_code": "US",
    "postal_code": "76474, 22272-0883",
    "address_line": "9802 West Tunnelchester",
    "city": "Diamondhead",
    "state_province": "Mississippi"
  },
  {
    "country": "United States",
    "iso_code": "US",
    "postal_code": "78145, 05478-9639",
    "address_line": "56359 Grovesfurt",
    "city": "Parsippany",
    "state_province": "New Hampshire"
  },
  {
    "country": "United States",
    "iso_code": "US",
    "postal_code": "31942, 83825-3466",
    "address_line": "955 East Valleysborough",
    "city": "South San Francisco",
    "state_province": "California"
  },
  {
    "country": "United States",
    "iso_code": "US",
    "postal_code": "62787, 62400-3317",
    "address_line": "757 Forgesberg",
    "city": "East Chicago",
    "state_province": "Indiana"
  },
  {
    "country": "United States",
    "iso_code": "US",
    "postal_code": "04449, 12155-0091",
    "address_line": "62251 North Groveston",
    "city": "Rock Springs",
    "state_province": "Wyoming"
  }
]

Code Examples

JavaScript


// Fetch random addresses
async function getRandomAddresses(countryCode, count = 10) {
  const response = await fetch(`https://mocloc.com/api/v1/addresses/${countryCode}?count=${count}`);
  const addresses = await response.json();
  return addresses;
}

// Usage example
getRandomAddresses('US', 5).then(addresses => {
  console.log('Generated addresses:', addresses);
});

Python


import requests
def get_random_addresses(country_code, count=10):
    url = f"https://mocloc.com/api/v1/addresses/{country_code}"
    params = {"count": count}
    response = requests.get(url, params=params)
    return response.json()

# Usage example
addresses = get_random_addresses("US", 5)
print(f"Generated {len(addresses)} addresses")

Java (Spring Boot)


@RestController
public class AddressController {
    
    @Autowired
    private RestTemplate restTemplate;
    
    @GetMapping("/generate-addresses")
    public ResponseEntity<List<Address>> generateAddresses(
            @RequestParam String countryCode,
            @RequestParam(defaultValue = "10") int count) {
        
        String url = "https://mocloc.com/api/v1/addresses/" + countryCode + "?count=" + count;
        Address[] addresses = restTemplate.getForObject(url, Address[].class);
        
        return ResponseEntity.ok(Arrays.asList(addresses));
    }
}

Rate Limits & Usage

Free Usage

No authentication required for basic usage

Rate Limits

100 requests per minute per IP address

Batch Limits

Maximum 50 addresses per request

Error Handling

The API uses standard HTTP status codes to indicate success or failure of requests.

200 Success

Request completed successfully

400 Bad Request

Invalid parameters or request format

404 Not Found

Country code not found or invalid endpoint

429 Too Many Requests

Rate limit exceeded