With the [GraphHopper Directions API](https://www.graphhopper.com/products/) you can integrate A-to-B route planning, turn-by-turn navigation, route optimization, isochrone calculations and other tools in your application. The GraphHopper Directions API consists of the following RESTful web services: * [Routing API](#tag/Routing-API), * [Route Optimization API](#tag/Route-Optimization-API), * [Isochrone API](#tag/Isochrone-API), * [Map Matching API](#tag/Map-Matching-API), * [Matrix API](#tag/Matrix-API), * [Geocoding API](#tag/Geocoding-API) and * [Cluster API](#tag/Cluster-API). # Explore our APIs ## Get started 1. [Sign up for GraphHopper](https://support.graphhopper.com/a/solutions/articles/44001976025) 2. [Create an API key](https://support.graphhopper.com/a/solutions/articles/44001976027) Each API part has its own documentation. Jump to the desired API part and learn about the API through the given examples and tutorials. In addition, for each API there are specific sample requests that you can send via Insomnia or Postman to see what the requests and responses look like. ## Insomnia To explore our APIs with [Insomnia](https://insomnia.rest/), follow these steps: 1. Open Insomnia and Import [our workspace](https://raw.githubusercontent.com/graphhopper/directions-api-doc/master/web/restclients/GraphHopper-Direction-API-Insomnia.json). 2. Specify [your API key](https://graphhopper.com/dashboard/#/register) in your workspace: Manage Environments -> Base Environment -> `"api_key": your API key` 3. Start exploring ![Insomnia](./img/insomnia.png) ## Postman To explore our APIs with [Postman](https://www.getpostman.com/), follow these steps: 1. Import our [request collections](https://raw.githubusercontent.com/graphhopper/directions-api-doc/master/web/restclients/graphhopper_directions_api.postman_collection.json) as well as our [environment file](https://raw.githubusercontent.com/graphhopper/directions-api-doc/master/web/restclients/graphhopper_directions_api.postman_environment.json). 2. Specify [your API key](https://graphhopper.com/dashboard/#/register) in your environment: `"api_key": your API key` 3. Start exploring ![Postman](./img/postman.png) ## API Client Libraries To speed up development and make coding easier, we offer the following client libraries: * [JavaScript client](https://github.com/graphhopper/directions-api-js-client) - try the [live examples](https://graphhopper.com/api/1/examples/) * [Others](https://github.com/graphhopper/directions-api-clients) like C#, Ruby, PHP, Python, ... automatically created for the Route Optimization API ### Bandwidth reduction If you create your own client, make sure it supports http/2 and gzipped responses for best speed. If you use the Matrix, the Route Optimization API or the Cluster API and want to solve large problems, we recommend you to reduce bandwidth by [compressing your POST request](https://gist.github.com/karussell/82851e303ea7b3459b2dea01f18949f4) and specifying the header as follows: `Content-Encoding: gzip`. This will also avoid the HTTP 413 error "Request Entity Too Large". ## Contact Us If you have problems or questions, please read the following information: - [FAQ](https://graphhopper.com/api/1/docs/FAQ/) - [Public forum](https://discuss.graphhopper.com/c/directions-api) - [Contact us](https://www.graphhopper.com/contact-form/) - [GraphHopper Status Page](https://status.graphhopper.com/) To stay informed about the latest developments, you can - follow us on [twitter](https://twitter.com/graphhopper/), - read [our blog](https://graphhopper.com/blog/), - watch [our documentation repository](https://github.com/graphhopper/directions-api-doc), - sign up for our newsletter or - [our forum](https://discuss.graphhopper.com/c/directions-api). Select the channel you like the most. # Map Data and Routing Profiles Currently, our main data source is [OpenStreetMap](https://www.openstreetmap.org). We also integrated other network data providers. This chapter gives an overview about the options you have. ## OpenStreetMap #### Geographical Coverage [OpenStreetMap](https://www.openstreetmap.org) covers the whole world. If you want to see for yourself if we can provide data suitable for your region, please visit [GraphHopper Maps](https://graphhopper.com/maps/). You can edit and modify OpenStreetMap data if you find that important information is missing, e.g. a weight limit for a bridge. [Here](https://wiki.openstreetmap.org/wiki/Beginners%27_guide) is a beginner's guide that shows how to add data. If you have edited data, we usually consider your data after 1 week at the latest. #### Supported Vehicle Profiles The Routing, Matrix and Route Optimization APIs support the following vehicle profiles: Name | Description | Restrictions | Icon -----------|:----------------------|:--------------------------|:--------------------------------------------------------- car | Car mode | car access | ![car image](https://graphhopper.com/maps/img/car.png) small_truck| Small truck like a Mercedes Sprinter, Ford Transit or Iveco Daily | height=2.7m, width=2+0.4m, length=5.5m, weight=2080+1400 kg | ![small truck image](https://graphhopper.com/maps/img/small_truck.png) truck | Truck like a MAN or Mercedes-Benz Actros | height=3.7m, width=2.6+0.5m, length=12m, weight=13000 + 13000 kg, hgv=yes, 3 Axes | ![truck image](https://graphhopper.com/maps/img/truck.png) scooter | Moped mode | Fast inner city, often used for food delivery, is able to ignore certain bollards, maximum speed of roughly 50km/h | ![scooter image](https://graphhopper.com/maps/img/scooter.png) foot | Pedestrian or walking without dangerous [SAC-scales](https://wiki.openstreetmap.org/wiki/Key:sac_scale) | foot access | ![foot image](https://graphhopper.com/maps/img/foot.png) hike | Pedestrian or walking with priority for more beautiful hiking tours and potentially a bit longer than `foot`. Walking duration is influenced by elevation differences. | foot access | ![hike image](https://graphhopper.com/maps/img/hike.png) bike | Trekking bike avoiding hills | bike access | ![bike image](https://graphhopper.com/maps/img/bike.png) mtb | Mountainbike | bike access | ![Mountainbike image](https://graphhopper.com/maps/img/mtb.png) racingbike| Bike preferring roads | bike access | ![racingbike image](https://graphhopper.com/maps/img/racingbike.png) Please note: * all motor vehicles (`car`, `small_truck`, `truck` and `scooter`) support turn restrictions via `turn_costs=true` * the free package supports only the vehicle profiles `car`, `bike` or `foot` * up to 2 different vehicle profiles can be used in a single optimization request. The number of vehicles is unaffected and depends on your subscription. * we offer custom vehicle profiles with different properties, different speed profiles or different access options. To find out more about custom profiles, please [contact us](https://www.graphhopper.com/contact-form/). * a sophisticated `motorcycle` profile is available up on request. It is powered by the [Kurviger](https://kurviger.de/en) Routing API and favors curves and slopes while avoiding cities and highways. ## TomTom If you want to include traffic, you can purchase the TomTom Add-on. This Add-on only uses TomTom's road network and historical traffic information. Live traffic is not yet considered. If you are interested to learn how we consider traffic information, we recommend that you read [this article](https://www.graphhopper.com/blog/2017/11/06/time-dependent-optimization/). Please note the following: * Currently we only offer this for our [Route Optimization API](#tag/Route-Optimization-API). * In addition to our terms, you need to accept TomTom's [End User License Aggreement](https://www.graphhopper.com/tomtom-end-user-license-agreement/). * We do *not* use TomTom's web services. We only use their data with our software. [Contact us](https://www.graphhopper.com/contact-form/) for more details. #### Geographical Coverage We offer - Europe including Russia - North, Central and South America - Saudi Arabia - United Arab Emirates - South Africa - Australia #### Supported Vehicle Profiles Name | Description | Restrictions | Icon -----------|:----------------------|:--------------------------|:--------------------------------------------------------- car | Car mode | car access | ![car image](https://graphhopper.com/maps/img/car.png) small_truck| Small truck like a Mercedes Sprinter, Ford Transit or Iveco Daily | height=2.7m, width=2+0.4m, length=5.5m, weight=2080+1400 kg | ![small truck image](https://graphhopper.com/maps/img/small_truck.png)
Positioning API accepts requests with radio network measurements and replies with corresponding location estimate. For more details and examples, see [Developer's Guide](https://developer.here.com/documentation/positioning). Cellular measurements are given in terms defined in 3GPP and 3GGP2 specifications, see the corresponsing documentation at http://www.3gpp.org. Breaking changes from v1: - JSON fields `altaccuracy`, `baselat`, `baselng`, `cellparams`, `pilotpower`, `pnoffset`, `powrx`, `rxlevel`, have been deprecated and replaced with `altAccuracy`, `baseLat`, `baseLng`, `cellParams`, `pilotPower`, `pnOffset`, `rss`, `rxLevel` respectively. - Dependent parameters combined as a subobject. - CDMA, GSM, WCDMA, TD-SCDMA and LTE local identification parameters for serving cell moved under `localId` property. - GSM neighbor global ID: `lac` and `cid` for neighbor cell moved under `globalIdentity` property.
# Getting Started ## Overview ### Access All API methods are either a `GET`, `POST` or `OPTIONS` request. The API communicates over both HTTPS and plain HTTP using IPv4 and IPv6. We recommend using HTTPS only although HTTP is available. We use appropriate HTTP status codes where possible to indicate the request status. ### Rate Limiting Each IP address is rate limited at 30 requests per second. Tripping the rate limit will result in a 503 response. The autocomplete API also has an additional rate limit. If you expect to breach the limit please contact us and we can move you to an endpoint with a higher limit. ### JSONP [JSONP](http://en.wikipedia.org/wiki/JSONP) requests are supported. Include a `callback=` in your request as a query parameter. Your results return wrapped in a function designated by your request. ## Authentication Most requests require an **API key** for authentication. Authenticate by passing an `api_key` as part of the query string. For example: ``` api.ideal-postcodes.co.uk/v1/autocomplete/addresses?api_key=iddqd&q=parkside ``` Alternatively, authentication can be transmitted via the `Authorization` header using the following scheme: ``` Authorization: api_key="iddqd" [other_key="foo"] ``` ## Versioning This API is versioned with a simple prefix in the URL. The current version is `/v1/`. We will maintain backwards-compatibility by releasing breaking changes under a new version. Please note that the following changes are backwards-compatible: - Adding new properties to existing API responses - Adding new API endpoints - Adding new optional request parameters to existing API endpoints - Changing the order of properties in existing API responses - Changing the autocomplete address suggestion format ## Error Handling A successful lookup is accompanied with a HTTP status code of 200 and a response code of 2000 (found in the body). An error has occurred if the HTTP status code is not 200. Errors can range from a benign 404 (resource not found) to more urgent errors (your API Key ran out of credit, failed authentication, etc). ## Testing Each new account comes with a free test balance. Contact us if you need more for testing and integration. ### Community Key Our documentation and demos make heavy use of our community key `iddqd`. This allows for convenient access for trialing the API. Many restrictions on this key are relaxed to allow developers make test requests. This key has a limit of 15 lookups per IP address per day as well as a daily usage cap. If you hit any limit restrictions, you can continue testing the API by creating a key of your own and using our free test methods. Please be kind with the community key. We're trusting everyone to use it responsibly so that other developers may trial the API. Thank you! ## Metadata Requests that affect your balance may be annotated with arbitrary metadata. This data is stored along with your lookup history and can be queried at a later date via the API or the dashboard. We call the ability to label your requests [tagging](https://docs.ideal-postcodes.co.uk/docs/guides/tags). # Response Codes The API returns two indicators to help you to determine the status of each HTTP request. The first is the **HTTP Status**, which is found in the status-line of all HTTP requests. The API will return status codes that adhere to HTTP /1.1 Specifications wherever possible. `2XX` status codes indicates success while `4XX` and `5XX` indicate client and server errors respectively. The second is the **API response code**, which can be found in the `code` property of the response body. This code will provide a more specific reason if a failure has occurred and can point you in the right direction when debugging. Please use the glossary of code numbers and HTTP status codes below when debugging your requests. ## 200 Request Success | HTTP Code | API Code | Description | | --------- | -------- | -------------------------------------------- | | 200 | 2000 | Success. Request was completed successfully. | ## 400 Bad Request The request could not be understood due to some input error. | HTTP Code | API Code | Description | | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | 400 | 4000 | Invalid syntax submitted. Some part of your request was malformed or did not match our specifications. | | 400 | 4001 | Validation failed on your submitted data. Some of the data you provided did not meet our validation requirements, e.g. string length. | | 400 | 4005 | Invalid start date. Please ensure start dates are provided as a UTC Timestamp in milliseconds. | | 400 | 4006 | Invalid end date. Please ensure end dates are provided as a UTC Timestamp in milliseconds. | | 400 | 4007 | Invalid date range. Check if your start and end dates are in the right order. | | 400 | 4008 | Invalid date range. Check that your date range is 90 days or less. | | 400 | 4009 | Too many tags. Please specify no more than 3 tags to query. | ## 401 Unauthorised Authorization credentials are not valid. | HTTP Code | API Code | Description | | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 401 | 4010 | Invalid Key. The `api_key` you provided is not valid. | | 401 | 4011 | Requesting URL not on whitelist. The cross domain request is not coming from a whitelisted URL. You can update or disable your allowed URLs via your Key settings. | | 401 | 4012 | Failed user authentication. Invalid `user_token` presented. | | 401 | 4013 | Licensee Key is required. Sublicensed keys require you need to present licensee credentials via the `licensee` parameter. | ## 402 Request Failed Your request is well-formed but are not able to complete your request for another reason. | HTTP Code | API Code | Description | | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 402 | 4020 | Key balance depleted. You're out of lookups on your API Key. | | 402 | 4021 | Limit reached. One of your lookup limits has been breached for today. This could either be your total daily limit on your key or the individual IP limit. You can either wait for for the limit to reset (after a day) or manually disable or increase your limit. | ## 404 Resource Not Found The resource you requested does not exist. | HTTP Code | API Code | Description | | --------- | -------- | --------------------------------------------------------------------------------------------- | | 404 | 4040 | Postcode not found. The postcode you have submitted does not exist. | | 404 | 4041 | User not found. Your user could not be identified given the credentials you presented. | | 404 | 4042 | Key not found. Your key could not be identified given the credentials you presented. | | 404 | 4044 | No UDPRN found. No address is associated with the UDPRN queried | | 404 | 4045 | No licensee found. Your licensee could not be identified given the credentials you presented. | | 404 | 4046 | No UMPRN found. No Multiple Residence premise is associated with the UMPRN queried. | ## 500 Server Error A error occurred on our server. | HTTP Code | API Code | Description | | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 500 | 5000 | An error occurred on our end. These errors are logged and queued so we can understand what went wrong. However, if you need speedy resolution please email support | | 500 | 5001 | Akin to 5000. | | 500 | 5002 | The server took too long to process on our end, so we aborted the request. You may retry the request. |
Add room selling to your app with ease, or expand your existing hotel portfolio. Access all the marketing material you need to sell a room, from hotel amenities to images. Constantly updated, ever expanding and always correct. Impala allows you to start selling hotel rooms and earn a commission with every booking in hours. Getting started is easy: > **1. Sign-up within seconds**: Head to the [Impala website](https://impala.travel), enter your details and receive your sandbox API key immediately (no credit card needed). > **2. Start building within minutes**: Build against a sandbox API with realistic test data. Use a [step-by-step walkthrough](https://impala.travel) to see what's possible. Check for available hotels and their rates. Make and manage fake bookings without any risk. Add room booking to your existing website or app, or start an online travel agency from scratch. [![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/11303451-9b241872-9961-424d-9ef4-9d949534567d?action=collection%2Ffork&collection-url=entityId%3D11303451-9b241872-9961-424d-9ef4-9d949534567d%26entityType%3Dcollection%26workspaceId%3D5ae55f12-332c-4e7d-8acc-3e75df3b2ee2) > **3. Go live within hours**: Once your app or integration is ready for prime time, move to production within your Impala dashboard and start making real hotel bookings for your customers right away. Want to see how it all works? Watch [a 5-minute walkthrough](https://www.youtube.com/watch?v=7B3evCL3nrY) of the two API requests you need to make a booking, and a demo of one of our customer's apps.