PHPackages what3words/w3w-php-wrapper - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. what3words/w3w-php-wrapper ActiveLibrary[API Development](/categories/api) what3words/w3w-php-wrapper ========================== A PHP library to use the what3words RESTful API v3.5.2(5mo ago)29583.1k—3.2%14[1 issues](https://github.com/what3words/w3w-php-wrapper/issues)[1 PRs](https://github.com/what3words/w3w-php-wrapper/pulls)2MITPHPPHP >=7.4CI passing Since Nov 23Pushed 3mo ago14 watchersCompare [ Source](https://github.com/what3words/w3w-php-wrapper)[ Packagist](https://packagist.org/packages/what3words/w3w-php-wrapper)[ Docs](https://github.com/what3words/w3w-php-wrapper)[ RSS](/packages/what3words-w3w-php-wrapper/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (5)Dependencies (1)Versions (19)Used By (2) [![what3words](https://camo.githubusercontent.com/d42660bc86f81adc673e8a8259b138921f06a3e169d0110b0e08e48327508d4b/68747470733a2f2f7768617433776f7264732e636f6d2f6173736574732f696d616765732f7733775f7371756172655f7265642e706e67)](https://camo.githubusercontent.com/d42660bc86f81adc673e8a8259b138921f06a3e169d0110b0e08e48327508d4b/68747470733a2f2f7768617433776f7264732e636f6d2f6173736574732f696d616765732f7733775f7371756172655f7265642e706e67) w3w-php-wrapper ======================================================================================================================================================================================================================================================================================================================================================================================================================================================================= [](#w3w-php-wrapper) A PHP library to use the [what3words REST API](https://docs.what3words.com/api/v3/). Overview ======== [](#overview) The what3words PHP wrapper gives you programmatic access to - convert a 3 word address to coordinates - convert coordinates to a 3 word address - autosuggest functionality which takes a slightly incorrect 3 word address, and suggests a list of valid 3 word addresses - obtain a section of the 3m x 3m what3words grid for a bounding box. - determine the currently support 3 word address languages. Authentication -------------- [](#authentication) To use this library you’ll need to obtain an API key, please visit and sign up for an account. Installation ============ [](#installation) #### Composer [](#composer) To use this library in your project, place the following line in your composer.json: ``` "what3words/w3w-php-wrapper": "3.*" ``` #### Manual [](#manual) To manually include this file, place [Geocoder.php](https://github.com/what3words/w3w-php-wrapper/blob/master/src/Geocoder.php) into your project, and `require_once("Geocoder.php")` ### Initialise [](#initialise) ``` use What3words\Geocoder\Geocoder; use What3words\Geocoder\AutoSuggestOption; $api = new Geocoder(""); ``` #### Options [](#options) You can also provide header values and referer (for restricted API keys). ``` use What3words\Geocoder\Geocoder; use What3words\Geocoder\GeocoderOptions; $options = GeocoderOptions::referer("https://my.site.com/*")->headers(["X-Custom-Header: my.site.com"]); $api = new Geocoder("", $options); ``` Convert To Coordinates ---------------------- [](#convert-to-coordinates) Convert a 3 word address to a position, expressed as coordinates of latitude and longitude. This function takes the words parameter as a string of 3 words `'table.book.chair'` The returned payload from the `convertToCoordinates` method is described in the [what3words REST API documentation](https://docs.what3words.com/api/v3/#convert-to-coordinates). #### Code Example [](#code-example) ``` $result = $api->convertToCoordinates("index.home.raft"); print_r($result); ``` Convert To 3 Word Address ------------------------- [](#convert-to-3-word-address) Convert coordinates, expressed as latitude and longitude to a 3 word address. The returned payload from the `convertTo3wa` method is described in the [what3words REST API documentation](https://docs.what3words.com/api/v3/#convert-to-3wa). #### Code Example [](#code-example-1) ``` $result = $api->convertTo3wa(51.432393,-0.348023); print_r($result); ``` Available Languages ------------------- [](#available-languages) This function returns the currently supported languages. It will return the two letter code ([ISO 639](https://en.wikipedia.org/wiki/ISO_639)), and the name of the language both in that language and in English. The returned payload from the `convertTo3wa` method is described in the [what3words REST API documentation](https://docs.what3words.com/api/v3/#available-languages) #### Code Example [](#code-example-2) ``` $result = $api->availableLanguages(); print_r($result); ``` Grid Section ------------ [](#grid-section) Returns a section of the 3m x 3m what3words grid for a given area. The requested box must not exceed 4km from corner to corner, or a BadBoundingBoxTooBig error will be returned. Latitudes must be >= -90 and <= 90, but longitudes are allowed to wrap around 180. To specify a bounding-box that crosses the anti-meridian, use longitude greater than 180. Example value: 50.0, 179.995, 50.01, 180.0005. The returned payload from the `gridSection` function is described in the [what3words REST API documentation](https://docs.what3words.com/api/v3/#grid-section) #### Code Example [](#code-example-3) ``` $result = $api->gridSection(39.903795, 116.384550, 39.902718, 116.383122); print_r($result); ``` AutoSuggest ----------- [](#autosuggest) Returns a list of 3 word addresses based on user input and other parameters. This method provides corrections for the following types of input error: - typing errors - spelling errors - misremembered words (e.g. singular vs. plural) - words in the wrong order The `autoSuggest` method determines possible corrections to the supplied 3 word address string based on the probability of the input errors listed above and returns a ranked list of suggestions. This method can also take into consideration the geographic proximity of possible corrections to a given location to further improve the suggestions returned. ### Input 3 word address [](#input-3-word-address) You will only receive results back if the partial 3 word address string you submit contains the first two words and at least the first character of the third word; otherwise an error message will be returned. ### Clipping and Focus [](#clipping-and-focus) We provide various `clip` policies to allow you to specify a geographic area that is used to exclude results that are not likely to be relevant to your users. We recommend that you use the clipping to give a more targeted, shorter set of results to your user. If you know your user’s current location, we also strongly recommend that you use the `focus` to return results which are likely to be more relevant. In summary, the clip policy is used to optionally restrict the list of candidate AutoSuggest results, after which, if focus has been supplied, this will be used to rank the results in order of relevancy to the focus. The returned payload from the `autosuggest` method is described in the [what3words REST API documentation](https://docs.what3words.com/api/v2/#autosuggest-result). ### Usage [](#usage) The first parameter is the partial three words, or voice data. It is followed by an array of AutoSuggestOption objects. The last parameter is the completion block. The AutoSuggestOption objects in the array are created using static convenience functions of the form: ``` AutoSuggestOption::fallbackLanguage("de"); AutoSuggestOption::focus($latitude, $longitude); ``` #### Code Example #1 [](#code-example-1-1) ``` $result = $api->autosuggest("fun.with.code"); print_r($result); ``` #### Code Example #2 [](#code-example-2-1) Focus on (51.4243877,-0.34745) and look for 6 results. ``` $result = $api->autosuggest("fun.with.code", [AutoSuggestOption::focus(51.4243877,-0.34745), AutoSuggestOption::numberResults(6)]); print_r($result); ``` #### Code Example #3 [](#code-example-3-1) Validate what3words ``` $result = $api->isPossible3wa("filled.count.soap"); print_r($result); // yields 1 $result = $api->isPossible3wa("not a 3wa"); print_r($result); // yields 0 $result = $api->findPossible3wa('from "index.home.raft" to " "filled.count.soap"'); print_r(implode(", ", $result)); // yields "index.home.raft, filled.count.soap" $result = $api->isValid3wa('filled.count.soapp'); print_r($result ? $result : 'invalid'); // yields 'invalid' ``` Handling Errors --------------- [](#handling-errors) All the functions will return an stdClass Object containing the requested data, or on failure, they will return `false`. If `false` is returned, call `get_error()`, and it will return an associative array containing a `code` value and a `message` value. ``` print_r($api->getError()); ``` Error values are listed in the [what3words REST API documentation](https://docs.what3words.com/api/v3/#error-handling). Development (using Docker) -------------------------- [](#development-using-docker) You can see `w3w-php-wrapper` in action by running `docker compose watch` (make sure you're running this from the `development` directory) and open on your browser. Any changes you make to the source code will be reloaded as you refresh your browser, just ensure you have loaded your environment variable named: `W3W_API_KEY` by running `export W3W_API_KEY=`. ``` $ export W3W_API_KEY=KEYFROMW3W $ docker compose watch [+] Building 0.6s (18/18) FINISHED [+] Running 1/1 ✔ Container php-server Started 0.0s Watch configuration for service "server": - Action sync for path "/w3w-php-wrapper/development/src" - Action sync for path "/w3w-php-wrapper/src" - Action sync for path "/w3w-php-wrapper/tests" ``` ### Running tests (using Docker) [](#running-tests-using-docker) Once you've spin up the container, you can run `docker exec php-server /var/www/html/vendor/bin/phpunit` to execute the unit tests. ``` $ docker exec php-server /var/www/html/vendor/bin/phpunit PHPUnit 5.5.4 by Sebastian Bergmann and contributors. ...................... 22 / 22 (100%) Time: 1.57 seconds, Memory: 3.25MB OK (22 tests, 25 assertions) ``` ### Health Score 59 — FairBetter than 99% of packages Maintenance74 Regular maintenance activity Popularity49 Moderate usage in the ecosystem Community27 Small or concentrated contributor base Maturity72 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~281 days Recently: every ~136 days Total 14 Last Release 172d ago Major Versions v1.0.5 → v2.0.02016-06-10 v2.2.0 → v3.0.02019-03-19 PHP version history (3 changes)v1.0.5PHP >=5.4 v3.5.0PHP >=5.6 v3.5.2PHP >=7.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/739adcb58c97b7e0b3db28cc2b151a88cb62131da461dc009193c7fba06a956d?d=identicon)[what3words](/maintainers/what3words) --- Top Contributors [![vicchi](https://avatars.githubusercontent.com/u/442617?v=4)](https://github.com/vicchi "vicchi (22 commits)")[![tsamaya](https://avatars.githubusercontent.com/u/1741320?v=4)](https://github.com/tsamaya "tsamaya (13 commits)")[![dave-w3w](https://avatars.githubusercontent.com/u/46780785?v=4)](https://github.com/dave-w3w "dave-w3w (6 commits)")[![chaddgrimm](https://avatars.githubusercontent.com/u/5126038?v=4)](https://github.com/chaddgrimm "chaddgrimm (4 commits)")[![thiswilliam](https://avatars.githubusercontent.com/u/9928155?v=4)](https://github.com/thiswilliam "thiswilliam (4 commits)")[![what3wordsgit](https://avatars.githubusercontent.com/u/7292787?v=4)](https://github.com/what3wordsgit "what3wordsgit (1 commits)")[![peterchaula](https://avatars.githubusercontent.com/u/13304490?v=4)](https://github.com/peterchaula "peterchaula (1 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![victorlap](https://avatars.githubusercontent.com/u/1645632?v=4)](https://github.com/victorlap "victorlap (1 commits)")[![simonw3w](https://avatars.githubusercontent.com/u/35031779?v=4)](https://github.com/simonw3w "simonw3w (1 commits)") --- Tags geocodingwhat3words3 word address ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/what3words-w3w-php-wrapper/health.svg) ``` [![Health](https://phpackages.com/badges/what3words-w3w-php-wrapper/health.svg)](https://phpackages.com/packages/what3words-w3w-php-wrapper) ``` ### Alternatives [willdurand/geocoder-bundle Integration of Geocoder into Symfony 3226.4M12](/packages/willdurand-geocoder-bundle)[alexpechkarev/google-geocoder Simple Google Geocoding API v3 wrapper for Laravel 4/5, Slim3 etc 74255.5k](/packages/alexpechkarev-google-geocoder)[opencage/geocode A PHP library for geocoding via the OpenCage Geocoder API 37480.0k4](/packages/opencage-geocode)[jcf/geocode Google Geocoding API for Laravel 48160.5k](/packages/jcf-geocode)[biscolab/google-maps-php-sdk Google Maps PHP SDK. 14215.1k](/packages/biscolab-google-maps-php-sdk)[riverside/php-nominatim PHP client for Nominatim, a search engine for OpenStreetMap data. 1225.9k1](/packages/riverside-php-nominatim) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)