Skip to main content

​
Frequently asked questions

Answers to common questions about submitting APIs, contributing to the project, and using the directory.

​
Submissions

Yes, you can submit your own API as long as it meets the requirements:
  • Has full free access or at least a free tier
  • Does not require purchasing a device or service
  • Has proper, publicly accessible documentation
  • Is not primarily a marketing attempt
The Public APIs list is a community resource, not a marketing platform. Submit your API if it provides genuine value to developers.
A public API is one that:
  • Has publicly accessible documentation
  • Can be accessed by anyone (with or without authentication)
  • Offers free access or a free tier
  • Doesn’t require purchasing hardware or proprietary services
Example of what NOT to submit: An API that controls a smart outlet. Even if the API is free, you must purchase the smart device, so it doesn’t qualify.
Yes, but only if it has a free tier that allows meaningful use without payment.
  • ✔ API with free tier (e.g., 1000 requests/month free)
  • ✔ API with limited free access for development
  • ❌ API that only offers a free trial
  • ❌ API that requires payment for any use
Common reasons for PR rejection:
  1. Marketing attempt - PR identified as primarily promotional
  2. Requires purchase - API depends on buying a device or service
  3. No free tier - API requires payment for all usage
  4. Duplicate entry - API already listed in the directory
  5. Failed validation - Build checks didn’t pass
  6. Poor documentation - API lacks proper public documentation
  7. Wrong format - Entry doesn’t follow required format
  8. Multiple APIs - More than one API submitted per PR
Review times vary based on:
  • Number of pending PRs in the queue
  • Maintainer availability
  • Whether your PR passes automated checks
  • Whether changes are requested
You can help speed up the process by:
  • Ensuring all automated checks pass
  • Following the format exactly
  • Providing complete, accurate information
  • Responding quickly to any feedback

​
Formatting

Every entry in the directory is an API, so adding “API” to the title is redundant.
  • ❌ Incorrect: GitHub API
  • ✔ Correct: GitHub
This keeps titles concise and consistent across all entries.
Domain names make titles unnecessarily long and less readable.
  • ❌ Incorrect: Gmail.com
  • ✔ Correct: Gmail
The actual domain is included in the link URL, so there’s no need to repeat it in the title.
You must shorten it. The 100-character limit ensures descriptions are:
  • Concise and scannable
  • Fit well in the table format
  • Easy to read at a glance
Tips for shortening:
  • Focus on the core functionality
  • Remove unnecessary words (“API that allows you to…” → “Service to…”)
  • Use abbreviations where appropriate
  • Cut marketing language
Consistent spacing makes the raw Markdown readable and easier to edit.Correct:
| [Gmail](link) | Email API | `apiKey` | Yes | Yes |
Incorrect:
|[Gmail](link)|Email API|`apiKey`|Yes|Yes|
The spaces don’t affect how the table renders, but they make the source file much easier to work with.
Choose the category that best matches the API’s primary purpose.Guidelines:
  • If an API fits multiple categories, choose the most relevant one
  • Don’t create a new category unless absolutely necessary
  • Look at similar APIs to see where they’re categorized
  • When in doubt, ask in your PR comments
Example: Instagram is listed under “Social” (not “Photography”) because it’s primarily a social network.

​
Authentication

apiKey:
  • Simple key/token authentication
  • Usually obtained from developer dashboard
  • Sent with each request (header, query param, etc.)
  • Good for server-to-server communication
OAuth:
  • User authorization flow
  • Requires user consent
  • Uses access tokens
  • Good for accessing user data on their behalf
If unsure, check the API’s authentication documentation.
List the primary or recommended authentication method.If an API supports both apiKey and OAuth, choose:
  • OAuth if it’s the recommended method
  • apiKey if it’s the simpler, default method
You can mention additional auth options in the API’s documentation.
This means the API requires you to send a User-Agent header identifying your application.Example:
curl -H "User-Agent: MyApp/1.0 ([email protected])" https://api.example.com
This is common for APIs (like Wikipedia) that want to know who’s using their service but don’t require formal registration.
Use the closest match from the allowed values:
  • OAuth - for any OAuth-like flow (OAuth 1, OAuth 2, etc.)
  • apiKey - for API keys, tokens, bearer tokens, etc.
  • X-Mashape-Key - only for RapidAPI/Mashape platform
  • User-Agent - for User-Agent header requirements
If none fit, use apiKey as it covers most authentication types.

​
CORS and HTTPS

Test it:
  1. Open browser developer console on any website
  2. Try making a request to the API: 
    fetch('https://api.example.com/endpoint')
  .then(r => r.json())
  .then(console.log)
  3. If it works → Yes
  4. If you get CORS error → No
  5. If unsure → Unknown
Check headers:
curl -I https://api.example.com/endpoint
Look for Access-Control-Allow-Origin header.
CORS determines whether the API can be used in browser-based JavaScript applications.With CORS (Yes):
  • Can use in web apps, browser extensions, client-side JavaScript
  • Direct API calls from frontend code
Without CORS (No):
  • Server-side only (Node.js, Python, etc.)
  • Browser blocks direct requests
  • Need a proxy server
This information helps developers quickly know if an API will work for their use case.
You can still submit it, but mark HTTPS as No.However, be aware that:
  • HTTP APIs are less secure
  • May not work in modern browsers (mixed content blocking)
  • Should be used with caution
  • May be less likely to be accepted
HTTPS is the modern standard and strongly preferred.
Yes, use Unknown for the CORS value.However, it’s helpful to test it if possible. The community and maintainers may update it later once confirmed.

​
Pull Requests

Squashing keeps the git history clean and readable.Without squashing:
Add API
Fix typo
Fix another typo
Update description
Fix formatting
With squashing:
Add GitHub API to Development category
See the GitHub guide on squashing for instructions.
Use: Add API-name APIExamples:
  • ✔ Add Blockchain API
  • ✔ Add GitHub API
  • ❌ Update README.md
  • ❌ Added new API
  • ❌ Add GitHub
Be descriptive and specific:
  • ❌ Update Readme.md
  • ✔ Add Blockchain API to Cryptocurrency
  • ✔ Add Weather API to Weather category
The commit message should clearly describe what was added and where.
No, submit one API per Pull Request.Reasons:
  • Easier to review
  • Clearer git history
  • If one API has issues, others aren’t blocked
  • Simpler discussion and feedback
Submit multiple PRs if you want to add multiple APIs.
  1. Click “Details” on the failed check in your PR
  2. Read the error messages in the build log
  3. Fix the issues in your local repository
  4. Commit and push the fixes
  5. Wait for checks to run again automatically
Common build failures:
  • Link validation errors (broken URL)
  • Format validation errors (wrong structure)
  • Alphabetical order errors
  • Duplicate links
See Validation tools for more details.
Generally no, unless:
  • Fixing a broken link
  • Correcting incorrect information
  • Updating CORS/HTTPS status
Don’t:
  • Replace old API version with new version (old gets deprecated)
  • Change description for marketing purposes
  • Change category without good reason

​
Using the directory

By category:
  • Use the Index at the top of the README
  • Click on category links to jump to that section
By keyword:
  • Use your browser’s find function (Ctrl+F or Cmd+F)
  • Search GitHub’s interface
By filters:
  • Check the website version if available
  • Look for community tools that provide filtering
An API might not be listed because:
  • No one has submitted it yet (you can!)
  • It was submitted but didn’t meet requirements
  • It requires payment with no free tier
  • It lacks proper documentation
  • It’s too new and hasn’t been discovered
The directory is community-maintained, so coverage depends on contributions.
No. The Public APIs directory is a community-curated list, not an endorsement.This means:
  • Inclusion doesn’t guarantee quality
  • No official support or warranty
  • APIs may change or shut down
  • Always check the API’s own documentation
  • Test thoroughly before production use
Do your own research before using any API in production.
The directory is updated continuously as:
  • New PRs are merged
  • Broken links are fixed
  • New APIs are discovered
There’s no fixed release schedule - it’s an ongoing community effort.

​
Still have questions?

Join our Discord

Get help from the community and maintainers

GitHub Issues

Search existing issues or ask a new question

Contributing Guide

Read the full contribution guidelines

Build docs developers (and LLMs) love

Get started for freeTalk to us