I wrote an custom contact import script for our NGO. The old contact data only contains valid country / state abbreviation names. For example CH / ZH = Switzerland / Zürich.

When I now want to create a new address over the API I don't see a way to fill out the 'state_province_id' field.

I'm able to get the country id with this syntax:

$result = civicrm_api3('Country', 'getsingle', array(
        'sequential' => 1,
        'return' => "id",
        'iso_code' => $row["V"],

   $params["api.address.create"][0]["country_id"] = $result["id"];

But how can I do the same with the State/Province, since there is no entity I can choose in the API?

5 Answers 5


Alternative way is if you use the table civicrm_state_province and the CRM_Core_DAO Class, something like this:

$query = "SELECT id FROM civicrm_state_province WHERE country_id = %1 AND abbreviation = %2";
$params = array(
  1 => array($countryId, 'Integer'),
  2 => array($abbreviationFromSource, 'String'));
$stateProvinceId = CRM_Core_DAO::singleValueQuery($query, $params);

If there is no state/Province API you would have to create one? Assuming you put your import script into an extension, this is not very hard to do. Using civix you can do generate:api StateProvince Get and the codes files (which you then have to adjust) will be generated for you. If you want to know more check out http://wiki.civicrm.org/confluence/display/CRMDOC/Create+a+Module+Extension#CreateaModuleExtension-AddanAPIfunction

  • I have some time pressure right now, but if I find time in the end I will consider to create an extension of my importer. Commented Sep 15, 2015 at 16:59

I ended up just calling the internal method.

return CRM_Core_DAO::getFieldValue('CRM_Core_DAO_StateProvince',

Takes advantage of a higher level of abstraction than sql so possibly more future proof, but probably not as future proof as using a designated API.

Still seems like you can't find it in the API, although getOptions looks close https://issues.civicrm.org/jira/browse/CRM-15919.


As of January 2017, there is a StateProvince API in CiviCRM: see CRM-19688.



  • 1
    It would be helpful if you could edit your answer to provide more detail. As it stands it doesn't really answer the question. Commented Dec 20, 2016 at 13:49

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.