REFUGE Restrooms Getting Started: API Access & First Call (2026)

Getting started overview

This guide outlines the process for developers to begin using the REFUGE Restrooms API. The API provides access to a crowdsourced database of safe and inclusive restrooms, serving as a resource for transgender, intersex, and gender non-conforming individuals. This guide focuses on initial setup, including understanding API access, making your first request, and troubleshooting common issues. The REFUGE Restrooms API is free to use and does not require an API key for its primary public endpoints, simplifying the initial integration process for developers.

The API is a RESTful service, meaning it uses standard HTTP methods (like GET) to interact with resources (like restrooms) and returns data in JSON format. This approach allows for broad compatibility across various programming languages and platforms. Developers can query the database to find restrooms based on location, access type, and other criteria specified in the REFUGE Restrooms API documentation.

To get started quickly, follow these steps:

Create an account and get keys

For the primary read-only public endpoints of the REFUGE Restrooms API, developers are not required to create an account or obtain API keys. This design choice simplifies initial integration by removing authentication as a prerequisite for accessing the restroom directory. The API is intended to be publicly accessible to maximize its utility as a community resource.

This approach differs from many commercial APIs, which typically require an account and API keys for rate limiting, billing, and access control. Because the REFUGE Restrooms API is offered as a free public service, these mechanisms are not implemented for basic data retrieval. Developers can proceed directly to making requests without an initial signup process.

While standard API key authentication is not required for public endpoints, developers contributing data or using specialized administrative endpoints (if any are introduced in the future) should consult the official REFUGE Restrooms API documentation for specific instructions. The current documentation indicates that anonymous access is sufficient for querying restroom data.

Your first request

To make your first request to the REFUGE Restrooms API, you will use the primary endpoint for searching restrooms. This example demonstrates how to retrieve a list of restrooms without any specific search parameters, which will return a broad set of results.

The base URL for the API is https://www.refugerestrooms.org/api/v1. The endpoint for searching restrooms is /restrooms. Therefore, a basic request to list all restrooms would target https://www.refugerestrooms.org/api/v1/restrooms.

Using curl

curl is a command-line tool for making HTTP requests and is commonly used for testing APIs. To make your first request, open your terminal or command prompt and enter the following:

curl https://www.refugerestrooms.org/api/v1/restrooms

Upon executing this command, the API will return a JSON array containing restroom objects. Each object will include details such as the restroom's name, address, accessibility features, and directions. The response structure for a single restroom might look like this:

[
  {
    "id": 12345,
    "name": "Community Center Restroom",
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "90210",
    "accessible": true,
    "unisex": true,
    "directions": "Behind the main hall",
    "comment": "Well-maintained and spacious",
    "updated_at": "2023-01-15T10:00:00.000Z",
    "downvote": 0,
    "upvote": 5
  },
  // ... more restroom objects
]

Using a web browser

You can also make this initial request directly in your web browser. Simply open your browser and navigate to:

https://www.refugerestrooms.org/api/v1/restrooms

Your browser will display the JSON response directly. Depending on your browser's configuration or installed extensions, the JSON may be formatted for readability.

Adding search parameters

To refine your search, you can add query parameters to the /restrooms endpoint. For example, to search for restrooms near a specific location, you might use lat (latitude) and lon (longitude) parameters, along with an optional per_page parameter to control the number of results.

curl "https://www.refugerestrooms.org/api/v1/restrooms?lat=34.0522&lon=-118.2437&per_page=10"

This request searches for 10 restrooms near the specified latitude and longitude (approximately Los Angeles, CA). For a full list of available search parameters and their usage, refer to the REFUGE Restrooms API documentation on search fields.

Common next steps

After successfully making your first request, consider these common next steps to integrate the REFUGE Restrooms API more deeply into your application:

1. Explore Search and Filter Options: The API supports various parameters to refine restroom searches. Review the API documentation for search parameters to understand how to filter by location (latitude/longitude), accessibility, unisex status, and keywords. This will enable your application to provide more relevant results to users.

2. Integrate with Mapping Services: Many applications that utilize location-based data combine it with mapping services. You could integrate the restroom locations obtained from the API with a service like the Google Maps JavaScript API or ArcGIS API for JavaScript to display restrooms visually on a map. This enhances the user experience by providing geographical context.

3. Implement User Interface (UI) for Display: Design and develop a user interface to display the restroom information clearly and intuitively. This might involve listing restrooms with their details, showing them on a map, and providing directions. Consider how users will interact with the data, such as sorting by distance or filtering by specific amenities.

4. Consider Contributions (if applicable): While the primary focus is on consuming data, the REFUGE Restrooms project relies on community contributions. If your application design includes functionality for users to suggest new restrooms or update existing information, investigate any potential contribution endpoints or processes outlined in the official API documentation. Note that contribution endpoints may require authentication or specific permissions.

5. Error Handling and Rate Limits: Although the REFUGE Restrooms API is free and generally open, it's good practice to implement error handling in your application. This includes handling cases where the API might return an error status code or unexpected data. While specific rate limits are not prominently documented for public read access, designing your application to handle potential rate limiting gracefully is a standard practice for any API integration.

6. Stay Updated with API Changes: APIs can evolve over time. Regularly check the REFUGE Restrooms API documentation for updates, new features, or deprecations to ensure your integration remains compatible and takes advantage of the latest offerings.

Troubleshooting the first call

When making your first API call, you might encounter issues. Here are common problems and their solutions:

1. Connection refused or network error

• Problem: Your curl command or browser request fails with a message like "Connection refused," "Failed to connect," or a general network error.
• Solution:
  • Check internet connection: Ensure your device has an active internet connection.
  • Verify URL: Double-check that the URL https://www.refugerestrooms.org/api/v1/restrooms is typed correctly, including https://. A common mistake is using http:// instead of https://, which can lead to connection issues or redirects.
  • Firewall/Proxy: If you are on a corporate or restricted network, a firewall or proxy server might be blocking the request. Consult your network administrator or try from a different network.
  • API availability: Although rare, the API server might be temporarily down. Check the REFUGE Restrooms homepage or social media for any service status updates.

2. Empty or unexpected JSON response

• Problem: The API returns an empty JSON array ([]) or JSON that doesn't match the expected restroom structure.
• Solution:
  • No parameters: If you are using search parameters (e.g., lat, lon), try making a request without any parameters (https://www.refugerestrooms.org/api/v1/restrooms) to ensure the basic endpoint works and returns data.
  • Incorrect parameters: Review the REFUGE Restrooms API documentation for the exact spelling and expected values of your query parameters. Incorrect parameter names or malformed values can lead to no results or errors. For example, latitude and longitude values must be valid decimal numbers.
  • Geographic scope: If searching by lat and lon, the specified location might not have any restrooms in the database. Try a different, more populated location, or broaden your search radius if the API supports it (currently, search is based on proximity to a point, without an explicit radius parameter in the docs).

3. HTTP Status Codes other than 200 OK

• Problem: The API returns an HTTP status code like 400 (Bad Request), 404 (Not Found), or 500 (Internal Server Error).
• Solution:
  • 400 Bad Request: This usually indicates an issue with your request's format or parameters. Review your URL and parameters carefully against the API documentation for correct syntax.
  • 404 Not Found: This means the specific endpoint or resource you requested does not exist. Verify the base URL and endpoint path (e.g., /api/v1/restrooms) are correct.
  • 5xx Server Error: A 500-level error indicates a problem on the API server's side. This is typically beyond your control. Wait a few minutes and try the request again. If the issue persists, check the REFUGE Restrooms website for any service announcements.

4. JSON parsing issues

• Problem: Your application receives the JSON response but struggles to parse or interpret it.
• Solution:
  • Validate JSON: Use an online JSON validator to paste the raw response and check for syntax errors.
  • Review data structure: Compare the received JSON structure with the expected format described in the REFUGE Restrooms API documentation. Ensure your parsing logic accounts for arrays of objects and the specific field names.
  • Language-specific JSON parsers: Ensure you are using the correct JSON parsing library for your programming language (e.g., JSON.parse() in JavaScript, json.loads() in Python, ObjectMapper in Java).