If things are just not working for you, try following these steps to help track down the problem.

Step 1. Check Connection

First off, grab the entire URL of the endpoint that you're trying to call and stick it in a browser. This should include the protocol, domain name, endpoint path and parameters (such as API key and query string). For example:

Put it all in your address bar and hit go. If the call succeeds, you should see something like this come back:

{ ... "code": 200, "message": "OK", ...}

Don't worry too much if your response doesn't match the example above exactly. Just ensure that you're getting some JSON back, and that there are no browser or network errors. If your browser prompts you to download a file, download it and open it up in a text editor. If the contents of the file look like the text shown in the example above, then things are (at least partially) working.

See also: Web Browsers and JSON

If all looks OK at this point, please move on to the next step: Step 2. Check HTTP Status

If you get a Network Error, Internal Server Error or Service Unavailable message then you're probably not able to contact the API server. Some possible causes:

  • You may be behind a firewall and require a proxy to be configured. Check with your network administrator for the correct network configuration.
  • The URL you entered could be wrong. Double-check that the server address and protocol are correct. See Server Details for the correct server details.
  • The API server may be down or experiencing technical difficulties.

See also: HTTP Status Codes

If you get an Unauthorized, Forbidden or Account Inactive message:

  • Your API key may be wrong. Please double-check to ensure your registration was completed and that the key you entered was correct.
  • You may have reached rate or volume limits. See Limits for more information.
  • Your account may have been disabled for some reason. Please contact us if you think this may be the case.

See also: Authenticating

If your problem was not solved, please see our Support page for more ways to get help.

Step 2. Check HTTP Status

In the previous step, we checked that you were able to communicate with the API server. If your application is still not working, but your browser was able to communicate with the API server, please check that you are using exactly the same proxy (if applicable) and network configuration. Consult your language or platform documentation for information on how to configure these. If your browser is on a different computer to the one that you're executing your application on, please re-read Step 1. Check Connection on that machine. For example, if you're running a PHP script on a web server, try running a browser on the server machine.

If there is still a difference between how your browser and your application appear to be working, please check the HTTP status code returned to your application. How you do this depends on what language and library you are using to communicate with the API server.

Tip: Remember to check for language-level errors and exceptions. Never catch and smother exceptions. If your library functions return error codes, check to ensure they are all successful.

Some suggestions for various languages:

  • Java: If you're using the class, check the value of the getResponseCode() function.
  • JavaScript: If you're using the XMLHttpRequest class, check the value of the status property.
  • PHP: If you're using the HttpRequest class, check the value of the getResponseCode() function.
  • Ruby: If you're using the Net::HTTP class, check that the type of response object is Net::HTTPOK. For example:
    if not response.instance_of?(Net::HTTPOK)
        response.error! # raises an exception

If there is an HTTP status being returned other than 200 (OK), please check it against the table in HTTP Status Codes for possible reasons. If you are getting a 200 (OK), please move on to the next step.

Step 3. Check Response Message

If you're getting an HTTP 200 response code, then you should be getting at least some JSON back from the server. If this is not the case, check the following:

  • That you are using the correct function to retrieve the content of the HTTP request. See your language or platform documentation for how to do this.

    Try fetching the content of a popular website, such as Google, to determine if your HTTP client is working and configured correctly.

  • Ensure you are using an HTTP GET method, not HEAD.
  • If you're getting something back, but it's not JSON, have a look at what it is, there may be an error message embedded somewhere in it. If it appears to be HTML:
    • Ensure the URL is correct. See Server Details for the correct URL.
    • Some proxies can smother HTTP status codes and return an HTML error page instead. For example, some mobile or wireless broadband providers may present an out of credit or other portal page instead. Read the HTML message and look for an error.

If you are getting JSON back, then check the code and message parameters. Check this before you pass the message through any JSON-parsing libraries just in case there is a problem with the library. If you see an error message or error status code, check the endpoint's documentation for possible solutions.

If your problem was not solved, please see our Support page for more ways to get help.

Others Problems & Solutions

This section contains a list of common problems and their solutions. Before posting on the forums or contacting us, it's a good idea to check if your problem is described here first.

Problem Solution
When I enter an API endpoint URL in to my browser it prompts me to download a file. Some browsers don't display the JSON messages (the format that the API endpoints return) very well, and may assume that it is a file you want to download. You can either download the file and open it with a text editor to view it, or use a browser that does handle JSON well.

See also: Web Browsers and JSON for more information.

I am getting one of the following errors when I try to access the API:
  • Unauthorized
  • Forbidden
  • Not Found
  • Method Not Allowed
  • Internal Server Error
  • Service Unavailable
Each of these messages indicates an error accessing the API, either due to a server or authorisation problem. Please see the table of HTTP Status Codes for possible solutions.
I see an error such as Connection Refused, No Route To Host or other network error. Double-check that the endpoint URL is correct (see Server Details). If it's not that, you probably don't have a direct connection to the Internet. Please check that your network settings are correct and, if you require a proxy, that it is correctly configured. Please see your language/platform documentation on how to do this.
No listings are returned when I search Check the code and message properties returned in the JSON response message. If there was a problem, such as a validation error, then these properties should be populated. See the endpoint's documentation for possible solutions, or Status Codes and Messages.

Of course it is possible that there were simply no matches. Try searching for something very common. If you're searching for a location, make sure you have put it in the correct field (ie, location rather than query, and vice-versa).

Businesses outside the location I searched in are being returned. If the search engine is unable to understand the entered location, or there were no matching listings in that location, it may increase the search area. See Search Query Tips for more information.