Retrieves detailed location information for a given zip code or hash identifier. Returns state, city, address, and other related information for USA zip codes. The API searches for zip code information stored in the database and returns comprehensive location details including city, address, and area code.

Authentication

This endpoint requires authentication via the Authorization header. The Authorization header must be set to "XXXXXX" for successful authentication. For API key access, please contact info@softasium.com Requests without valid authorization will return an authorization failure response.

Request

• Method: POST
• Content-Type: application/x-www-form-urlencoded or application/json
• Parameters:
  • hash (string, required): The zip code or identifier to look up. Can be a standard 5-digit zip code (e.g., "90210") or a unique identifier.
• Headers:
  • Authorization (string, required): Must be "XXXXXX" for authentication. For API key access, please contact info@softasium.com

Response

• Content-Type: application/json
• Status Codes:
  • 200 OK: Request processed successfully (check status field for actual result)
  • 404 Not Found: No matching zip code data found

Data Model (ZipCodeModel)

The response follows the ZipCodeModel structure with the following fields:

• state_abbr (string, nullable): State abbreviation (e.g., "CA", "NY", "TX"). Returns null if no data found.
• state_name (string, nullable): Full state name (e.g., "California", "New York", "Texas"). Returns null if no data found.
• city (string, nullable): City name associated with the zip code. Returns null if no data found.
• local_name (string, nullable): Local area name or neighborhood. Returns null if no data found.
• address (string, nullable): Street address or location address. Returns null if no data found.
• zip_code (string, nullable): The zip code that was queried. Returns null if no data found.
• area_code (string, nullable): Area code for the location's telephone service. Returns null if no data found.
• status (boolean): Indicates the success status of the lookup. true for successful lookups, false for not found or authorization failures.
• message (string): Descriptive message indicating the result ("Data found", "No data found", or "Invalid Authorization Key!").
• code (string, optional): Present only in authorization failure responses. Contains the hash value that was sent in the request.

Success Response (200 OK)

When a valid zip code is found and authorization is successful, the API returns HTTP 200 OK with a JSON object containing all location details.

{
  "state_abbr": "CA",
  "state_name": "California",
  "city": "Beverly Hills",
  "local_name": "Beverly Hills",
  "address": "123 Main St",
  "zip_code": "90210",
  "area_code": "310",
  "status": true,
  "message": "Data found"
}

Example Requests

Here are example requests for different scenarios:

Successful Lookup (cURL)

curl -X POST https://api.softasium.com/api/ZipApi \
  -H "Authorization: XXXXXX" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "hash=90210"

Error Handling

The API uses different status codes and response structures to indicate various outcomes:

• 200 OK with status: true: Successful lookup with data found. All fields contain valid location information.
• 404 Not Found: The zip code does not exist in the database. All data fields are null, status is false, and message is "No data found".
• 200 OK with status: false and message: "Invalid Authorization Key!": Authentication failed. The Authorization header is missing or incorrect. The code field contains the hash value that was sent.

Best Practices

• Always include the Authorization header with the value "XXXXXX" in every request. For API key access, please contact info@softasium.com
• Check the status field in the response to determine if the lookup was successful, regardless of HTTP status code
• Handle null values in response fields when status is false
• Validate zip codes before sending requests (5-digit format recommended)
• Implement proper error handling for network issues and API failures
• Cache successful responses when appropriate to reduce API calls